Chronicler
Operations & security

Troubleshooting

The failures people actually hit, and what fixes each one.

First, look

PowerShell
docker compose ps
docker compose logs --tail 100
Invoke-RestMethod http://localhost:8410/health

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.

PowerShell
"POSTGRES_PASSWORD=$([guid]::NewGuid().ToString('N'))`nCOMPOSE_PROFILES=cpu" |
  Out-File -Encoding ascii .env
docker compose up -d
If the stack has run before, the existing password is the only key to the database volume. Don't generate a new one - find the original .env.

port is already allocated

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

PowerShell
docker ps -a | Select-String "chronicler"

Either stop the other thing, or move Chronicler:

.env
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.

PowerShell
Select-String "COMPOSE_PROFILES" .env

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:

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

If the list is empty, pull by hand:

PowerShell
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. It then stays loaded for 4 days (OLLAMA_KEEP_ALIVE), so only the first question after a restart pays it. If every answer after an idle spell is slow, something lowered that:

.env
OLLAMA_KEEP_ALIVE=96h

Every answer takes minutes

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

PowerShell
docker compose ps
nvidia-smi
docker stats --no-stream

See GPU acceleration and Performance and memory.

The GPU models are greyed out in Admin → Model

The console can't tell you have a graphics card. It probes from inside the backend container, which is given no access to the GPU on purpose - only the Ollama container gets it - so it's told what you have via CHRONICLER_GPU_VRAM_GB in your .env.

PowerShell
Select-String "COMPOSE_PROFILES|CHRONICLER_GPU_VRAM_GB" .env
  • COMPOSE_PROFILES=nvidia but no VRAM line: rerun the detection script, then docker compose up -d. Installs set up before this key existed won't have it until something writes it.
  • COMPOSE_PROFILES=cpu or amd: not a bug. The key is written only on nvidia, and the CPU-capable tiers really are all your stack can serve. Fix the profile first if the machine has an NVIDIA card.

You can set it by hand - whole GB, and it must match reality. Claiming 24 on a 12 GB card only moves the failure to load time.

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

Check the server itself

PowerShell
Invoke-RestMethod http://localhost:8410/health

Fails locally → the problem is the stack, see above.

Check from the other machine

PowerShell
Invoke-RestMethod http://192.168.1.50:8410/health

Fails → firewall or wrong address. On Windows, Docker Desktop and Windows Firewall both need to allow it.

Check the address in the app

Settings → Connection: mode Local, the full URL including http:// and the port. 192.168.1.50 alone won't work; http://192.168.1.50:8410 will.

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.

PowerShell
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

PowerShell
docker system df -v

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

PowerShell
docker image prune -a
docker exec chronicler-ollama ollama list
Never docker volume prune or docker compose down -v. Those delete postgres_data and backend_uploads - your entire install.

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:

PowerShell
docker compose down -v
docker compose up -d

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

Collecting information for support

PowerShell
docker compose ps | Out-File support.txt
docker compose logs --tail 500 | Out-File -Append support.txt
docker info --format "{{.MemTotal}} {{.KernelVersion}}" | Out-File -Append support.txt
docker compose config | Out-File -Append support.txt
docker compose config prints your database password. Remove it before sending the file to anyone.

Security and networking

Let colleagues in without letting everyone in.

Install the app

Download Chronicler for Windows or Linux.