Configuration & access

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.

Hardware

Variable	Description
`CHRONICLER_GPU_VRAM_GB`	VRAM of the graphics card, in whole GB. Set on the `nvidia` profile only. The backend container has no GPU access of its own, so without this Admin → Model reports no GPU and greys out the GPU-class models. The detection script and the desktop app both write it.

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`	`96h`	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

# So the admin console knows how big the card is
CHRONICLER_GPU_VRAM_GB=24

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

PowerShell

docker volume ls | Select-String "chronicler"
docker system df -v

Linux shell

docker volume ls | grep chronicler
docker system df -v

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

PowerShell

docker compose config
docker compose ps
docker compose logs backend

Linux shell

docker compose config
docker compose ps
docker compose logs backend

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.

Edit this page

Models

Which model writes your answers, how to change it, and what each one needs.

Licensing and activation

Activate your key, and understand the check that runs every 30 minutes.