Troubleshoot

Start with container state and logs. Run every command from deploy/compose with the same .env and Compose file used to start the hub.

export BEARICORN_COMPOSE_FILE=docker-compose.caddy.yml

docker compose --env-file .env -f "$BEARICORN_COMPOSE_FILE" ps
docker compose --env-file .env -f "$BEARICORN_COMPOSE_FILE" logs --tail=200
docker compose --env-file .env -f "$BEARICORN_COMPOSE_FILE" config --quiet

A container is restarting

Inspect only that service:

docker compose --env-file .env -f "$BEARICORN_COMPOSE_FILE" logs --tail=200 hub-app
docker compose --env-file .env -f "$BEARICORN_COMPOSE_FILE" logs --tail=200 postgres

Common causes include placeholder or mismatched database credentials, an incomplete image build, a failed migration, or a full disk.

df -h
docker system df

Do not delete volumes while troubleshooting. The postgres_data volume is the database.

PostgreSQL is unhealthy

docker compose --env-file .env -f "$BEARICORN_COMPOSE_FILE" exec postgres \
  sh -c 'pg_isready -U "$POSTGRES_USER" -d "$POSTGRES_DB"'

If .env database values were changed after the volume was created, revert them to the values that initialized the database or perform an intentional PostgreSQL role/database migration.

The domain does not open

From another network:

dig +short chat.example.com
curl -I http://chat.example.com
curl -I https://chat.example.com

Confirm that:

• DNS points to the server's current static public IP;
• provider and host firewalls allow TCP 80 and 443;
• no other process owns those ports; and
• CADDY_SITE_ADDRESS or TRAEFIK_HOST exactly matches the hostname.

sudo ss -lntp | grep -E ':(80|443)\b'

Caddy cannot obtain a certificate

docker compose --env-file .env -f docker-compose.caddy.yml logs --tail=200 caddy

Caddy needs public DNS and inbound reachability on both ports. A raw IP request does not match a domain-based site address.

Traefik routes fail

docker compose --env-file .env -f docker-compose.traefik.yml logs --tail=200 traefik

Check the router host, ACME email, Docker socket mount, and certificate challenge. Keep the insecure dashboard bound to loopback and inspect it through the SSH tunnel described in the Traefik guide.

Direct HTTP works but the external proxy does not

Test the app on the server first:

curl -I http://127.0.0.1:8080

Then inspect the external proxy. It must forward normal HTTP, WebSocket upgrades, the original host, and large attachment requests. Keep the Direct port private.

Collect a safe support bundle

Record container state, recent logs, the Git commit, and the redacted resolved Compose configuration. Remove passwords, JWT secrets, cookies, recovery phrases, invitation tokens, IP addresses, and personal content before sharing anything.