Troubleshooting

First, look

docker compose ps                  # what's running
docker compose logs --tail 100     # what went wrong
curl http://localhost:8410/health  # is the backend alive

Healthy looks like chronicler-postgres, chronicler-ollama and chronicler-backend up, and chronicler-ollama-pull exited — that last one downloads the model and stops, which is correct.

The stack won't start

POSTGRES_PASSWORD is missing a value

There's no .env next to the compose file, or it doesn't contain that line. Compose refuses to start rather than shipping a guessable default.

printf 'POSTGRES_PASSWORD=%s\nCOMPOSE_PROFILES=cpu\n' "$(openssl rand -hex 24)" > .env
docker compose up -d

port is already allocated

Something else has 8410, 11434 or 5432 — often an older Chronicler stack.

docker ps -a | grep chronicler     # an old stack?

Either stop the other thing, or move Chronicler:

BACKEND_PORT=8411

Then point the app at http://localhost:8411.

Cannot connect to the Docker daemon

Docker isn't running. Start Docker Desktop and wait for it to say it's ready.

The stack is up but nothing answers

Ollama did not come up ... within 2 minutes

COMPOSE_PROFILES is missing or misspelled, so no model runtime started. This is the single most common self-host failure.

grep COMPOSE_PROFILES .env     # must be cpu, nvidia or amd

Add or fix it, then docker compose up -d. Check with docker compose ps that one of ollama-cpu, ollama-nvidia or ollama-amd is running.

Chat returns errors, the log says model not found

The model download didn't finish. Watch it:

docker compose logs ollama-pull
docker exec chronicler-ollama ollama list

If the list is empty, pull by hand:

docker exec chronicler-ollama ollama pull gemma4:e2b

Everything 403s, or documents won't open

An unlicensed or lapsed licence. Admin → Licensing:

• No licence activated — paste your key.
• Active, but the app is still blocked — check Last checked. If it's more than 72 hours old, the server can't reach api.chroniclerlm.com. Fix outbound HTTPS; it recovers by itself.

See Licensing.

It's up but painfully slow

The first answer takes minutes

Normal on a CPU: the model has to load. Keep it loaded:

OLLAMA_KEEP_ALIVE=-1

Every answer takes minutes

Either you're on the CPU when you have a GPU, or the model is too big for the machine.

docker compose ps          # ollama-cpu, or ollama-nvidia?
nvidia-smi                 # does memory move while it's generating?
docker stats --no-stream   # is anything pinned at its limit?

See GPU acceleration and Performance and memory.

Containers keep restarting

Out of memory. docker stats shows what's being killed; raise Docker's memory allocation, or choose a smaller model. Under 4 GiB available to Docker, the backend cannot survive a model load.

The app can't reach the server

curl http://localhost:8410/health

curl http://192.168.1.50:8410/health

Documents get stuck processing

Large scanned files are slow — OCR is the expensive part, and on a CPU a 200-page scan can take a very long time.

docker compose logs backend --tail 100
docker stats --no-stream

If it's genuinely stuck rather than slow, restart the backend (docker compose restart backend) and re-upload. If it's every document, you're out of disk or out of the allocation set in Admin → Settings.

Disk is full

docker system df -v

Usual culprits: old images after several updates, and old models.

docker image prune -a          # unused images — safe
docker exec chronicler-ollama ollama list   # models you no longer use

I've forgotten the admin password

There's no recovery from the outside; the server never had a password you can look up. Another administrator can reset it from Admin → Users. If there's only one administrator and it's locked out, restore a backup from before the change, or start again from an empty database — which is why a second administrator account is worth having.

Starting over

Deletes everything:

docker compose down -v
docker compose up -d

Take a backup first if there's anything you want.

Collecting information for support

docker compose ps > support.txt
docker compose logs --tail 500 >> support.txt
docker info --format "{{.MemTotal}} {{.KernelVersion}}" >> support.txt
docker compose config >> support.txt