Self-hosting
Configuration reference
Every setting you can change, where it lives, and what is deliberately fixed.
Where settings live
| Where | What | Applies |
|---|---|---|
.env beside docker-compose.yml | Password, GPU profile, ports, versions, memory knobs | After docker compose up -d |
| Admin console | Model, embedding location, disk allocation, backups, licence, updates | Immediately |
| Baked into the image | Realm, sign-up policy, licence enforcement, embedding model, internal URLs | Not changeable |
The
.env file holds your database password. It is the only key to the
postgres_data volume — back it up, and never regenerate it on a running
install.Required
| Variable | Description |
|---|---|
POSTGRES_PASSWORD | Database password. No default ships. Compose refuses to start without it. |
COMPOSE_PROFILES | Which model runtime starts: cpu, nvidia or amd. Unset means no model runtime starts. |
Versions
| Variable | Default | Description |
|---|---|---|
CHRONICLER_VERSION | latest | Backend image tag. Pin it (e.g. 1.0.9) to make updates deliberate. |
OLLAMA_VERSION | 0.32.4 | Ollama image tag. |
The compose file you get from the desktop app or the release uses
CHRONICLER_VERSION. If you're working from the repository's
docker/docker-compose.yml instead, the equivalents are IMAGE_TAG and
IMAGE_NAMESPACE, and OLLAMA_GENERATION_MODEL selects which model is
pre-downloaded.Ports
| Variable | Default | Description |
|---|---|---|
BACKEND_PORT | 8410 | Where the app connects. Change if 8410 is taken. |
OLLAMA_PORT | 11434 | Model runtime. Only needs to be reachable from the stack itself. |
POSTGRES_PORT | 5432 | Database. Bound to 127.0.0.1 — not reachable from the network, by design. |
Memory and performance
Full explanations on Performance and memory.
| Variable | Default | Description |
|---|---|---|
OLLAMA_KEEP_ALIVE | 5m | How long the model stays in memory. -1 = forever. |
OLLAMA_NUM_PARALLEL | automatic | Concurrent requests per model. Multiplies context memory. |
OLLAMA_MAX_LOADED_MODELS | automatic | Models resident at once. |
OLLAMA_CONTEXT_LENGTH | 16384 | Default context for other clients. Does not change chat context. |
POSTGRES_SHARED_BUFFERS | 128MB | Database cache. |
POSTGRES_WORK_MEM | 4MB | Memory per sort. |
A variable you leave out is not passed to the container at all, so the runtime's own default applies. That's intentional — there's no way to accidentally set an empty value.
A complete example
.env
# Required
POSTGRES_PASSWORD=8f3c1d7a9b2e4c6f0a5d8e1b3c7f9a2d4e6b8c0f
COMPOSE_PROFILES=nvidia
# Pin the version so updates are deliberate
CHRONICLER_VERSION=1.0.9
# Memory: dedicated server, keep the model hot, four people
OLLAMA_KEEP_ALIVE=-1
OLLAMA_NUM_PARALLEL=4
POSTGRES_SHARED_BUFFERS=2GB
POSTGRES_WORK_MEM=16MB
Volumes
These three are your install. Everything else is disposable.
| Volume | Contents |
|---|---|
postgres_data | Database: accounts, documents, the search index. |
backend_uploads | Uploaded files, generated backups, the server's signing key and install id. |
ollama_data | Downloaded models. Large, and re-downloadable. |
Terminal
docker volume ls | grep chronicler
docker system df -v # how much space each one uses
docker compose down -v deletes these volumes and everything in them. Plain
docker compose down does not. There is no undo.Optional: an offsite backup folder
To have scheduled backups copied somewhere outside Docker, mount a host folder
into the backend container. Edit your docker-compose.yml, under the backend
service:
docker-compose.yml
volumes:
- backend_uploads:/app/uploads
- /mnt/nas/chronicler-backups:/mnt/backups
Then enter /mnt/backups as the offsite folder in Admin → Backups. Details:
Backups and restore.
What you can't change, and why
| Fixed | Why |
|---|---|
| Single-organisation mode | A self-hosted server serves one organisation. This is what makes accounts, sharing and licensing behave predictably. |
| No open sign-up | Accounts are created by an administrator, never self-serve. |
| Licence enforcement | On, always. It cannot be switched off from the compose file. |
| Central licence URL | Fixed, and responses are signed, so pointing the check at another server doesn't work. |
| Embedding model | Changing it would invalidate every index built with the old one. Baked into the image so it can never be missing. |
| Internal service URLs | The backend reaches the database and the model runtime over the stack's private network. |
The security-relevant ones are enforced inside the image, not in the compose file, so editing the compose file cannot turn them off.
Getting a clean look at your configuration
Terminal
docker compose config # the fully resolved file, all variables expanded
docker compose ps # what's running
docker compose logs backend # what the backend thinks
docker compose config is the honest answer to "did my .env actually take
effect" — it shows the values Compose resolved, not what you meant to write.