Common Deployment Problems

Common Deployment Problems

Read the api's log first (from v0.1.13)

The api checks its own setup and writes what it finds to its log (in Portainer: the api container → Logs). Lines starting with SETUP PROBLEM: say what's wrong and what to change, for example:

• FERNET_KEY missing or invalid, or no platform admin to sign in with;
• PUBLIC_BASE_URL still the default, or plain http;
• the server reached without an HTTPS reverse proxy (sign-in can't work), or a proxy that isn't trusted (FORWARDED_ALLOW_IPS);
• an integration half set up, or UPDATER_SHARED_SECRET missing or short;
• the DNS resolver unreachable, or no worker running.

Lines starting with SETUP TIP: name optional integrations you haven't set up (Microsoft sign-in, a Microsoft 365 mailbox, a hosted reporting mailbox, Cloudflare). They're fine to ignore.

Portainer: a variable I set isn't taking effect

You're likely on a Repository stack. Portainer only reads a stack.env file committed in the repo for those — variables typed into Portainer's UI are silently ignored, so ${...} placeholders fall back to their defaults. Switch to the Web editor method instead. Full detail → Deploying with Portainer.

Port :8000 already in use

Another instance, or something else on the host, already has it. Set API_HOST_PORT to a free port (CLI: in .env; Portainer: as an environment variable) and point your reverse proxy at that port instead.

Sessions/audit log show the reverse proxy's IP, not the real visitor's

Set FORWARDED_ALLOW_IPS to your reverse proxy's own IP — uvicorn only trusts the X-Forwarded-For header from an explicitly listed peer. Find the wrong IP currently being logged (a session's ip_address, or the sign-in audit log) and set this to that address.

Entra SSO redirect fails / "redirect URI mismatch"

PUBLIC_BASE_URL doesn't match what's registered in the Entra app's redirect URI, or was set/changed after the app registration was created. Get PUBLIC_BASE_URL right before configuring SSO — it's part of the OAuth redirect URI.

STARTTLS check: "Could not connect to :25"

The STARTTLS check connects to each MX host on port 25. Many cloud networks block outbound port 25: Azure does for every subscription type except Enterprise Agreement, and so do most VPS providers until you ask. Every domain then shows a STARTTLS error and a lower grade, though nothing is wrong with its mail. Set STARTTLS_CHECK_MODE=tls_rpt to take the result from the TLS-RPT reports senders send instead (the Azure default since v0.2.0), or off to skip it. Either way the port-25 test no longer runs.

Azure: Fernet key rejected by the deployment wizard

Fixed in v0.1.5 — an earlier version of the wizard's validation regex rejected every key the documented generate command produces (it excluded the base64 padding character =, which a real 32-byte key always ends in). If you're on an older release, pull the latest createUiDefinition.json or generate a key and strip trailing = padding is not the fix — regenerate against a current release instead.

---

← Troubleshooting & FAQ · Home