Skip to main content
Version: 2026.8.0

Troubleshooting

When something goes wrong on a self-hosted instance, three questions answer most of it:

  1. Is the stack running? docker compose ps
  2. What do the logs say? docker compose logs <service>
  3. Which piece is unhappy? The health check, then the page for that symptom under Find your fix.

Everything here assumes the two-file setup from Install: a .env, a docker-compose.yml, and docker compose in the folder that holds them.

Read the logs​

Logs are the first stop for almost every problem.

docker compose ps            # which containers are up, and their health
docker compose logs api      # one service
docker compose logs -f caddy # follow it live
docker compose logs --tail 50 api

Each container names itself in its log lines. A crash-looping container shows in docker compose ps as restarting, and its logs almost always print the reason on the last few lines before it exits.

The "is it up" check​

The API answers a health endpoint that needs no login:

curl -fsS http://localhost:8088/api/v1/healthz
  • A healthy instance returns JSON with "ok": true.
  • Changed WEB_PORT, or reach the box by an HTTPS address? Use that host and port instead.
  • A refused connection means the web or api container isn't up, so check docker compose ps and the api logs.

Find your fix​

  • Install and startup: a container won't start, a migration failed on boot, a port is already in use, image pulls are denied.
  • HTTPS and access: the certificate won't issue, the phone camera is blocked, a name resolves but won't load.
  • Data and backups: restoring, the encryption key, a backup that didn't run.
  • Common error messages: a table from the exact text you see to its cause and fix.

Day-two operations (updating, routine backups) live in Operating.

Where things live​

  • .env and docker-compose.yml are your whole configuration. Every setting is a line in .env, and changing one and running docker compose up -d applies it.
  • ./data/ holds all state, in one folder per service: db (the databases), files (uploads and images), backups (the stack's nightly dumps), caddy and caddy-config (issued certificates and proxy config), modules (installed module code). Copy this tree with the stack stopped and you have copied everything (see Data and backups).
  • The containers are db, api, web, and caddy (the last only when you run HTTPS). Nothing bind-mounts source code, because the images are what runs.