Self-hosting

Troubleshooting

The ways a first self-hosted deployment usually goes wrong, and where to look.

Desktops or devices can't connect at all

Almost always a proxy swallowing WebSocket upgrades. If the relay is behind a reverse proxy or load balancer, confirm it's configured to forward WebSocket connections through unbuffered; see Requirements. A proxy that works for ordinary HTTP traffic can still break this without any error.

/readyz never returns healthy

With MySQL storage, this means the relay can't reach the database: check -database (or FLOCKDECK_RELAY_DATABASE_URL), that the database exists, and -database-ca if the connection needs a CA certificate. With the embedded database, check that -data points at a directory the relay's process can actually write to.

Certificate errors

• Using -acme-domain: the relay needs to be reachable on ports 80 and 443 directly from the internet for the ACME challenge to complete. Behind a proxy or load balancer, use -tls-cert/-tls-key or terminate TLS at the proxy instead; see Deploying the relay.
• Using -tls-cert/-tls-key: the relay reloads these when they change, so check the files were actually replaced (not just touched) and that the process can read them.
• Using -desk-domain: this needs a wildcard certificate covering *.relay.example.com, not just the base domain.

A desktop registers against the shared relay instead of yours

FLOCKDECK_RELAY has to be set in the environment the copy of Flockdeck that's running was launched from. See Connecting desktops. A variable set in one shell profile doesn't reach Flockdeck launched from a desktop shortcut, a different shell, or a service manager. Passing -relay on flockdeck remote enable directly sidesteps this.

New desktops can't register

If -registration is invite, every new desktop needs a code from flockdeck-relay invite first; see Admin and invites. If it's closed, no new account can be created; closed stops new accounts, not joins with -join. Check -max-hosts too: it is per account, so a join fails once that account has that many desktops, until one is removed.

Rate limiting

-register-per-hour, -pair-per-minute and -connects-per-minute (see Configuration) are all per source address. Behind a proxy, if -trust-proxy isn't set, the relay sees every request as coming from the proxy's own address and rate-limits everyone behind it together. Turn it on, and make sure the proxy sets the forwarded headers it relies on.

Still stuck

Check that the relay reports itself healthy (/healthz and /readyz) before chasing anything else. A relay that isn't up yet produces symptoms that look like every problem above at once.