Troubleshooting

The dashboard and API must be HTTPS sibling subdomains, such as app.example.com and api.example.com. Sign out, clear old Upstand cookies, and sign in again after changing domains or updating the control plane. Session cookies are scoped to the shared parent domain only when the two hosts are siblings.

Installer reports a service is not ready

Run:

docker stack services upstand
docker service ps upstand_server --no-trunc
docker service logs upstand_server --tail 100

Do not delete volumes while investigating: they contain the control-plane state.

Caddy cannot issue a certificate

Check DNS and inbound 80/443 first. Then inspect docker logs upstand-caddy --tail 100. Existing services on those ports must be moved or stopped before Caddy can bind them.

A remote node does not receive a deployment

Confirm it is ready in Upstand and Ready in docker node ls. Deployment logs must show a matching node and placement constraint. If not, correct the saved address/hostname and rerun setup.

A deployment is stuck

Review deployment logs and service tasks. Upstand restores queued jobs after a restart, but a build that actually failed must be corrected and redeployed. Use the dashboard's queue cleanup only after confirming no legitimate deployment is active.

Database schema generation on Windows

Run bun db:generate from the repository root. The command supplies safe local Better Auth URLs automatically, so a local .env file is not required for schema generation. If you override the command, provide BETTER_AUTH_URL, CORS_ORIGIN, BETTER_AUTH_SECRET, and DATABASE_URL as valid values.