relay.md

Relay

Managed relay deployment for seamless mino.ink connectivity without requiring user-owned domains or open inbound ports.

← Back to docs

Why Relay Exists

Relay is the default connectivity mode for Mino:

  • User deploys server stack.
  • Server opens outbound connector to relay.
  • User opens generated mino.ink /link?relayCode=... URL.
  • Web client exchanges relay code, then talks to server through relay proxy routes.

No inbound port forwarding is required for the default flow.

Required Variables

Relay service (apps/relay)

VariableRequiredDefaultExample
RELAY_HOSTNo0.0.0.00.0.0.0
RELAY_PORTNo87878787
RELAY_PUBLIC_BASE_URLYes (recommended)nonehttps://relay.mino.ink

Server stack (apps/server) in relay mode

VariableRequiredDefaultExample
MINO_CONNECTION_MODEYesrelayrelay
MINO_RELAY_URLYeshttps://relay.mino.inkhttps://relay.mino.ink
MINO_PORT_BINDRecommended127.0.0.1127.0.0.1
MINO_PUBLIC_SERVER_URLNoemptyhttps://api.example.com

Web (Cloudflare Pages for test.mino.ink / mino.ink)

VariableRequiredExample
NEXT_PUBLIC_RELAY_URLYeshttps://relay.mino.ink
NEXT_PUBLIC_APP_ORIGINYeshttps://test.mino.ink
NEXT_PUBLIC_DEFAULT_LINK_TARGETYeshttps://test.mino.ink
NEXT_PUBLIC_APP_ENVYestest / production

Deployment Steps (Test Domain)

1. Deploy relay backend

Deploy ghcr.io/tomszenessy/mino-relay:main with:

  • RELAY_PUBLIC_BASE_URL=https://relay.mino.ink

Then verify:

  • GET https://relay.mino.ink/api/v1/health

2. Route relay hostname in Cloudflare Tunnel

If using cloudflared for relay exposure, add a published application route:

  • Subdomain: relay.test
  • Domain: mino.ink
  • Type: HTTP
  • URL: relay:8787

3. Update Cloudflare Pages (test.mino.ink)

Set:

  • NEXT_PUBLIC_RELAY_URL=https://relay.mino.ink

Redeploy Pages.

4. Update Mino server stack

Set:

  • MINO_CONNECTION_MODE=relay
  • MINO_RELAY_URL=https://relay.mino.ink
  • MINO_PORT_BIND=127.0.0.1

Redeploy server stack.

5. Connect

Use setup-generated links (logs or /api/v1/system/setup) and open:

  • https://test.mino.ink/link?relayCode=...&relayUrl=...

The link flow auto-exchanges pairing code and connects without manual serverUrl input.

First Deployment Checklist (From Zero)

Use this when only test.mino.ink (frontend) is running and relay/server are not deployed yet.

1. Start relay container

docker run -d --name mino-relay --restart unless-stopped \
  -p 8787:8787 \
  -e RELAY_PUBLIC_BASE_URL=https://relay.mino.ink \
  ghcr.io/tomszenessy/mino-relay:main

Expected:

  • container mino-relay is running

2. Expose relay.mino.ink to relay

Pick one:

  • Cloudflare Tunnel route to relay service (HTTP, URL relay:8787)
  • Reverse proxy / DNS to host port 8787

Expected:

  • https://relay.mino.ink/api/v1/health responds successfully

3. Configure Cloudflare Pages for test.mino.ink

Set build env variable:

  • NEXT_PUBLIC_RELAY_URL=https://relay.mino.ink

Then redeploy Pages.

4. Deploy one Mino server stack (relay mode)

In Portainer stack env vars:

  • MINO_CONNECTION_MODE=relay
  • MINO_RELAY_URL=https://relay.mino.ink
  • MINO_PORT_BIND=127.0.0.1

Deploy / redeploy stack.

5. Run the link flow

Open the setup link from server logs or setup endpoint:

  • https://test.mino.ink/link?relayCode=...&relayUrl=https://relay.mino.ink

Expected:

  • /link auto-connects
  • workspace opens without manual serverUrl entry

6. Quick failure checklist

  • If relay health fails: check relay container logs and route target.
  • If /link fails: verify NEXT_PUBLIC_RELAY_URL and MINO_RELAY_URL match.
  • If server does not appear online: verify server stack uses MINO_CONNECTION_MODE=relay.

Open-Port Fallback

For direct connectivity mode:

  • MINO_CONNECTION_MODE=open-port
  • MINO_PORT_BIND=0.0.0.0
  • optional MINO_PUBLIC_SERVER_URL=https://api.yourdomain.com

This enables direct serverUrl + apiKey links for mino.ink and local UI endpoints.