Troubleshooting

Start with service status and logs

Check the deployment as a whole first. When the symptom points to one service, follow that service’s logs instead of collecting unrelated output.

docker compose ps
docker compose logs --tail=100

Application does not open

• Confirm that the expected services are running with `docker compose ps`.
• Check Caddy logs for listener, routing, DNS, and certificate errors.
• Confirm the hostname resolves to this server and that inbound ports 80 and 443 are allowed.
• Confirm APP_DOMAIN and WEB_ORIGIN use the hostname users actually open.

docker compose logs caddy --tail=100

HTTPS certificate is not issued

• Confirm that public A and, when used, AAAA records resolve to reachable addresses on this server.
• Confirm ports 80 and 443 reach Caddy and are not intercepted by another service.
• Review Caddy logs for the certificate authority response.
• Check whether a CDN, proxy, or hosting firewall prevents hostname validation.

Application opens but actions fail

Inspect the failed browser request without copying cookies or secrets. Confirm WEB_ORIGIN matches the public origin, then review API and Caddy logs for the same time. A page can load even when an application request is rejected or misrouted.

docker compose logs api --tail=100
docker compose logs caddy --tail=100

Sign-in does not work

• Review API logs without printing passwords, password hashes, cookies, MFA secrets, or JWT values.
• Confirm WEB_ORIGIN, HTTPS, and secure-cookie settings match the public deployment.
• Confirm the account has an active community membership and complete any required MFA or password-change step.
• Confirm the server clock is synchronized so signed-session and MFA time checks are reliable.

Chat or realtime features do not connect

• Inspect the browser WebSocket request to `/socket.io` and note its status without exposing session cookies.
• Confirm Caddy receives and routes the realtime request.
• Leave the explicit realtime origin empty for the standard same-origin deployment, or confirm a custom value points to the correct public origin.
• Review API and Caddy logs for connection or authorization failures.

Background jobs are not processing

• Confirm that the worker and Redis services are running.
• Review worker and Redis logs for connectivity, queue, and job-specific errors.
• Check the affected workflow after the worker recovers; email and asynchronous media cleanup are examples of queued work.

docker compose logs worker --tail=100
docker compose logs redis --tail=100

Email is not being sent

• Review the saved community email settings: enabled state, SMTP host and port, secure/TLS mode, username, password, sender email, and sender name.
• Save changed settings before sending a test email.
• Review worker logs for connection, authentication, and provider errors.
• Confirm the server can reach the provider’s outbound SMTP port. Some hosting providers restrict outbound SMTP independently of the server firewall.

Uploaded files are unavailable

• Confirm that the uploads volume exists and is mounted at the configured uploads path.
• Confirm the Compose project name has not changed and selected a different named volume.
• Check free disk space and review API logs for filesystem or permission errors.
• Do not edit Docker volume contents manually; recover files from a verified matching backup.

Data appears missing after redeployment

Changing COMPOSE_PROJECT_NAME can make Docker Compose select a different set of named volumes, causing an existing installation to appear empty. Stop before creating new community data, identify the original project name and volumes, and consult Docker Compose before reconnecting them.

Database or migration startup fails

• Confirm PostgreSQL is running and accepting the configured database credentials.
• Review PostgreSQL and API logs for the first migration or connection error.
• Do not edit applied migration history or repeatedly force migrations without understanding the database state.
• Create or verify a backup before destructive database recovery.

docker compose logs postgres --tail=100
docker compose logs api --tail=100

Disk space is low

• Use `df -h` to inspect host filesystems and `docker system df` to understand Docker disk usage.
• Identify whether PostgreSQL data, uploads, images, or logs are consuming space before deleting anything.
• Move or expire data according to an intentional retention plan. Do not run blanket volume-pruning commands against a production installation.

df -h
docker system df

A service keeps restarting

• Inspect the service status and its latest 200 log lines.
• Check required environment values, PostgreSQL and Redis reachability, migration errors, and malformed configuration.
• For Caddy, also check public port conflicts and hostname configuration.
• Fix the first reported cause rather than increasing restart delays or repeatedly recreating containers.

docker compose ps
docker compose logs <service> --tail=200