Skip to main content

Troubleshooting

When something goes wrong on a self-hosted instance, three questions answer most of it: is the stack running, what do the logs say, and which piece is unhappy. This page covers those, then points at the specific fixes.

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

Where things live​

  • .env and docker-compose.yml are your whole configuration. Every setting is a line in .env; 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), caddy and caddy-config (issued certificates and proxy config), modules (installed module code). Copy this tree 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; the images are what runs.

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; 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. If you changed WEB_PORT or you 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; 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.