Troubleshooting

Server commands are run from the installation folder.

The site doesn't open

1. docker compose ps — are all services running? If not: docker compose up -d.
2. docker compose logs --tail=100 caddy — certificate errors or API connection errors.
3. DNS: the domain points to the server IP (or to Cloudflare with the proxy on).
4. The firewall allows 80 and 443: sudo ufw status.

Error 502

Caddy works but the API doesn't. docker compose logs --tail=200 api — a common cause is the API failing to connect to the database. docker compose restart api.

Certificate is not issued

• In Cloudflare turn off “Always Use HTTPS”, SSL mode Full (strict). See Cloudflare.
• The DNS record for the subdomain (admin, docs) must exist before start.
• Port 80 must be open: the domain is verified through it.

The admin panel refuses access

Your IP is not on the list. Owner — add it to ADMIN_ALLOWED_IPS in .env and run docker compose up -d caddy. Operator — ask the owner to add your IP in Staff → Sign-in. Behind Cloudflare the engine sees your real IP; if it changes (mobile internet), use a VPN with a fixed address.

2FA code doesn't work

Check the time on your phone (automatic) and on the server (timedatectl). Codes depend on accurate time.

Rates don't update

System status → Rates. docker compose logs --tail=200 worker. The worker may have stopped: docker compose up -d worker.

Emails are not sent

Mail → “Check”. Common causes: wrong port (465 — TLS, 587 — STARTTLS), password, sender not on a verified domain.

Telegram notifications don't arrive

• TELEGRAM_BOT_TOKEN is set in .env, and api and worker were restarted after the change.
• The bot is in the chat and the chat ID is right (groups start with -100).
• Notifications → Logs — Telegram's response to the send.

A backup failed

System status → Backups and the “Backup error” event. Common causes: low disk space (df -h), BACKUP_PASSWORD not set. docker compose logs --tail=200 worker.

Low disk space

docker image prune -f — remove old images. Shorten backup retention in Backups. Don't delete Docker volumes.

Nothing helped

Collect docker compose ps, the last 200 log lines of api, worker, caddy and the /api/health response and contact OneSwaper support. Never send the .env file, passwords or keys. API logs may contain links with one-time tokens (staff invitations, sign-in) and order numbers — mask them before sending.