# Chronos Server with Docker Chronos Server in a container next to PostgreSQL 17, from `deploy/docker/docker-compose.yml`. For Unraid see [unraid.md](unraid.md); the settings below are the same there. ## Install ```sh mkdir chronos && cd chronos curl -LO https://gitea.encke-hake.ts.net/BalboSoft/Chronos/raw/branch/main/deploy/docker/docker-compose.yml curl -L -o .env https://gitea.encke-hake.ts.net/BalboSoft/Chronos/raw/branch/main/deploy/docker/.env.example # edit .env: CHRONOS_ADMIN_PASSWORD, CHRONOS_DB_PASSWORD, CHRONOS_ARCHIVE, PUID/PGID, TZ docker login gitea.encke-hake.ts.net # while the organisation is private docker compose up -d ``` 1. Create the archive folder on the host, owned by `PUID:PGID` (`mkdir -p /srv/timelapse && chown 1000:1000 /srv/timelapse`). An empty folder, or one owned by root (Docker creates a missing bind source that way), is given to `PUID:PGID` at start: the folder itself, never its contents. Any other folder that user cannot write stops the container with a one-line error naming it. 2. Open `http://:8080/admin`, sign in as `admin` with `CHRONOS_ADMIN_PASSWORD` and choose a new password (a change is required at the first sign-in). Without `CHRONOS_ADMIN_PASSWORD` the first start writes a temporary password to `/data/initial-admin-password.txt`, readable only by its owner, never to the log; the file goes once an administrator changes their password. Both variables are read only while no administrator exists. 3. In Settings › Network and TLS copy the **Client address** (by default `https://:8443`) into Chronos and the Uploader, and compare the certificate **Fingerprint** at their first connection. `.env` holds the passwords and the host folders: `CHRONOS_ARCHIVE` (archive, default `./archive`), `CHRONOS_DATA` (`./data`), `CHRONOS_VIDEOS` (videos folder, `./videos`), `CHRONOS_PGDATA` (PostgreSQL's files, `./pgdata`), `PUID`, `PGID` (default 1000) and `TZ` (default UTC). These four folder names are Compose's, not the server's. ## Image and tags `gitea.encke-hake.ts.net/balbosoft/chronos-server`, built for `linux/amd64`. | Tag | What it is | Use it for | |---|---|---| | `:latest` | The highest stable release; before the first stable release (`v1.0.0`), the highest pre-release | Production; the compose file and the Unraid template use it | | `:` (`:1.0.0`, `:0.1.0-rc.14`) | Exactly that release | Pinning, rolling back | | `:nightly` | `main` as it was at 02:17 that night (version `0.0.0-nightly.`); never a release | Trying what is not released yet; not for production | `docker run --rm gitea.encke-hake.ts.net/balbosoft/chronos-server:latest --help` lists every variable the server reads. ## Volumes | Container path | Holds | Required | |---|---|---| | `/archive` | The archive: originals, sidecars (`.chronos/` folders), proxies, renders, trash. Readable without Chronos | Yes | | `/data` | `server.json`, the TLS certificate (`tls/server.pfx`), uploads in progress, logs (`logs/`), `initial-admin-password.txt` | Yes | | `/videos` | Copies of renders made by *Copy to videos folder* (admin panel › Videos, the desktop's Videos section), flat, hash-checked, " (2)" on a name collision. Chronos never deletes what it copied there | No: with `CHRONOS_VIDEOS_PATH=/videos` | | `/space` | Read-only view of the volume whose free space the admin panel shows (Unraid's array view) | No: with `CHRONOS_SPACE_PATH=/space` | - `/archive` and `/data` are image volumes; `/videos` and `/space` are not, so an image run without them makes no anonymous volume. A `/videos` that is not a mounted volume, or that `PUID:PGID` cannot write, only warns at start: copying then fails with its reason in the admin panel, and everything else runs. - The videos folder must lie outside the archive and the data folder; the admin panel refuses another, and a copy then answers `videos_folder_invalid`. Remove `CHRONOS_VIDEOS_PATH` and the volume to turn copying off. - The server writes into the archive's `.chronos` folders at once (staging, trash, locks). One left to root (an earlier run as root, a copy made as root) stops the start with an error naming it; fix it on the host with `chown -R : /.chronos`. Nothing inside the archive is ever chowned by the container. ## Environment variables Every server setting comes from, in order: its default, `/data/server.json`, then the environment. **A variable that is set fixes its setting:** the admin panel shows the field read-only and its tooltip names the variable. Leave a variable unset to choose the value in the admin panel while the server runs. A value out of range stops the start with a message naming the variable. | Variable | Default | Meaning | |---|---|---| | `CHRONOS_DATA_PATH` | `/data` (Windows: `C:\ProgramData\Chronos Server`) | Data folder; read before `server.json`, which lives in it | | `CHRONOS_ARCHIVE_PATH` | `/archive` (Windows: `C:\ChronosArchive`) | Archive folder | | `CHRONOS_SPACE_PATH` | unset: the archive's volume | A folder whose volume's free space the admin panel shows (`/space`). One that cannot be measured falls back to the archive's with one warning. Uploads always check the archive's own volume (507 when full) | | `CHRONOS_VIDEOS_PATH` | unset: copying off (`videos_folder_unset`); compose sets `/videos` | Absolute folder *Copy to videos folder* writes into, outside the archive and the data folder | | `CHRONOS_SERVER_NAME` | `Chronos Server` | Name shown to clients and announced on the LAN | | `CHRONOS_ADMIN_USER` | `admin` | First administrator, created only while none exists (letters, digits, `.`, `-`, `_`) | | `CHRONOS_ADMIN_PASSWORD` | unset: a temporary password in `/data/initial-admin-password.txt` | Its first password; a change is required at the first sign-in | | `CHRONOS_DB` | `postgres` (Windows: `sqlite`) | `postgres`, `sqlite` (Windows only) or a full connection string (`Host=…;Port=…;Database=…;Username=…;Password=…`), which wins over the parts below | | `CHRONOS_DB_HOST` | `postgres` | PostgreSQL host | | `CHRONOS_DB_PORT` | `5432` | PostgreSQL port | | `CHRONOS_DB_NAME` | `chronos` | Database, owned by the user below | | `CHRONOS_DB_USER` | `chronos` | PostgreSQL role | | `CHRONOS_DB_PASSWORD` | unset | Its password (SCRAM, MD5, cleartext and trust are understood) | | `CHRONOS_DB_SSLMODE` | `prefer` | `disable`, `prefer`, `require` or `verify-full` | | `CHRONOS_HTTP_PORT` | `8080` | Port the server listens on for HTTP. In a container (the image sets it) only this variable changes it, which matters only with host networking | | `CHRONOS_HTTPS_PORT` | `8443` | Port the server listens on for HTTPS; as above | | `CHRONOS_PUBLIC_HTTP_PORT` | unset: the HTTP port | Host port clients use for HTTP when the container's 8080 is published as another; LAN discovery announces it | | `CHRONOS_PUBLIC_HTTPS_PORT` | unset: the HTTPS port | Host port clients use for HTTPS: the port of the client address, of the admin panel's redirect to HTTPS and of LAN discovery | | `CHRONOS_TLS_MODE` | `auto` | `auto` (self-signed, made at first start), `pem` (your certificate) or `proxy` (plain HTTP behind a TLS-terminating reverse proxy) | | `CHRONOS_TLS_CERT` | unset | `pem` mode: path of the certificate (PEM, full chain) inside the container | | `CHRONOS_TLS_KEY` | unset | `pem` mode: path of its private key (PEM) | | `CHRONOS_TRUSTED_PROXIES` | `127.0.0.0/8, ::1/128` | `proxy` mode: addresses or CIDR networks of the proxies whose `X-Forwarded-*` headers count; see [TLS](#tls) | | `CHRONOS_LANG` | `en` | Language of the server's messages when the client's own language is not one Chronos ships | | `CHRONOS_PARALLELISM` | half the logical cores (1–64) | Photos the running job processes at once; jobs run one at a time. `CHRONOS_WORKERS`, its former name, still sets it with a warning | | `CHRONOS_PRIORITY_QUEUE` | `false` | `true`: a job of a higher kind pauses the running one, which resumes by itself afterwards | | `CHRONOS_DISCOVERY` | `true` | LAN discovery beacon (UDP); it leaves a container only with host networking | | `CHRONOS_LOG_LEVEL` | `Information` | `Trace`, `Debug`, `Information`, `Warning`, `Error`, `Critical` or `None` (also `info`, `warn`, `off`): the log files' and the console's level, locking both | | `CHRONOS_LOG_CONSOLE_LEVEL` | the log level | The console's (the container log's) level alone; wins over `CHRONOS_LOG_LEVEL` for the console | | `CHRONOS_LOG_RETENTION_DAYS` | `14` (1–3650) | Days log files in `/data/logs` are kept | | `CHRONOS_LOG_MAX_FILE_MB` | `50` (0–10240, 0 = no limit) | Size at which a log file continues in `.1.log`, `.2.log`… | | `CHRONOS_LOG_MAX_TOTAL_MB` | `1024` (0–1048576, 0 = no limit) | Size of all log files together; the oldest go beyond it, never the current one | | `CHRONOS_LOG_ROTATION` | `daily` | `daily` or `hourly` log files (UTC): `server-yyyyMMdd.log` | | `CHRONOS_AUDIT_RETENTION_DAYS` | `0` = forever (0–3650) | Days of audit log the *Audit log clean-up* schedule keeps; set, it is applied to that schedule at every start | | `CHRONOS_DIAGNOSTICS_LOG_MB` | `4` (1–1024) | MB from the end of each log file in the diagnostics zip (admin panel › Logs › *Diagnostics*) | | `PUID` / `PGID` | `1000` / `1000` | User and group the server runs as; the data folder is given to them | | `TZ` | `UTC` | Time zone of the schedules and of the folders of photos without a capture time; logs stay in UTC | ## Ports The server listens on **8080** (HTTP: admin panel and API) and **8443** (HTTPS: the API Chronos and the Uploader use) inside the container. Those two stay as they are on a bridge network: the admin panel shows them read-only, and a value `server.json` held for them is ignored with a warning and removed at the next save. The **public ports** are the host ports clients reach. | Situation | Compose `ports` | Public ports | Clients use | |---|---|---|---| | Default | `"8080:8080"`, `"8443:8443"` | leave empty | `https://:8443` | | Another service uses 8080 and 8443 on the host (the owner's Unraid case) | `"8087:8080"`, `"8444:8443"` | Public HTTP port **8087**, Public HTTPS port **8444** | `https://:8444`; admin panel `http://:8087/admin` | | Host networking (`network_mode: host`) | none (ignored) | leave empty | `https://:8443`, or the port set with `CHRONOS_HTTPS_PORT` | - Keep the container side of a mapping (after the colon) at 8080 and 8443. Change only the host side, then enter the same host ports as **Public HTTP port** and **Public HTTPS port** in Settings › Network and TLS, or set `CHRONOS_PUBLIC_HTTP_PORT` / `CHRONOS_PUBLIC_HTTPS_PORT` (which then lock them). They apply at once: the client address, the redirect to HTTPS and LAN discovery name the ports clients can reach. - An address typed in a client without a scheme or port (`nas.local`) means port 8443; `https://nas.local` alone means 443 (a reverse proxy). Type the client address as the admin panel shows it. - LAN discovery reaches clients only with host networking: on a bridge network its broadcasts stay inside Docker, and clients type the client address. With host networking the port mappings do nothing, the server listens on the host's 8080 and 8443 itself and does not start when another service already uses either: set `CHRONOS_HTTP_PORT` / `CHRONOS_HTTPS_PORT` to free ports and leave the public ports empty. The name `postgres` no longer resolves there: publish PostgreSQL on loopback (`ports: ["127.0.0.1:5432:5432"]` under `postgres`) and set `CHRONOS_DB_HOST: 127.0.0.1`. ## TLS | Mode | What happens | Clients | |---|---|---| | `auto` (default) | A self-signed certificate is made at first start in `/data/tls/server.pfx`, valid five years, made anew 30 days before it expires; its SHA-256 fingerprint is logged and shown in Settings › Network and TLS › **Fingerprint** | Trust on first use: the client shows the fingerprint once; compare it with the admin panel's | | `pem` | Your certificate and key: mount them read-only (`./certs:/certs:ro`) and set `CHRONOS_TLS_CERT=/certs/fullchain.pem`, `CHRONOS_TLS_KEY=/certs/privkey.pem`, readable by `PUID:PGID`. Restart after renewing them | A certificate a public CA signed is trusted at once | | `proxy` | Plain HTTP on 8080 behind a reverse proxy that terminates TLS | `https://` | - The fingerprint changes when `/data` is lost or the self-signed certificate is renewed: clients then ask again. Compare before accepting; keep `/data` in the backup so it does not change by surprise. - An address that answers but is not Chronos (another service on that port) is reported as *not a Chronos server*, and its certificate is never offered for trust. - Behind a proxy only the proxies listed in `CHRONOS_TRUSTED_PROXIES` may set `X-Forwarded-*` headers; by default only loopback, since other machines on the LAN reach the HTTP port directly and must not choose the address the sign-in limit and the audit log see. Give a proxy container a fixed address on a user-defined network it shares with Chronos (`ipv4_address` in compose, *Fixed IP address* on Unraid), list that address (`172.30.0.10`), and let it reach Chronos on that network rather than through a published port. Never list a subnet, the network's gateway (`.1`) or Docker's default bridge (`172.17.0.0/16`). A proxy on the Docker host itself: run Chronos with host networking. The admin panel shows *Not via proxy* when a page did not come through a trusted proxy over HTTPS. ## PostgreSQL Chronos Server on Linux needs PostgreSQL 16 or 17 (`CHRONOS_DB=sqlite` is Windows only). The compose file runs the official `postgres:17` image with its files in `CHRONOS_PGDATA`, and waits for it to be healthy; the server retries the connection for about 30 seconds more before it stops. To use an existing PostgreSQL instead, remove the `postgres` service and `depends_on`, create a role and a database it owns (`CREATE ROLE chronos LOGIN PASSWORD '…'; CREATE DATABASE chronos OWNER chronos;`) and set `CHRONOS_DB_HOST`, `CHRONOS_DB_PORT`, `CHRONOS_DB_NAME`, `CHRONOS_DB_USER`, `CHRONOS_DB_PASSWORD` and, for a remote one, `CHRONOS_DB_SSLMODE=require` or `verify-full`. Or give a whole connection string in `CHRONOS_DB`. ## Upgrading 1. Back up first: at least the database and `/data` ([below](#backup-and-restore)). 2. `docker compose pull && docker compose up -d`. 3. The server migrates the database at start; the log shows `Database Postgres ready, schema version N`. Jobs in progress resume from their last checkpoint. - Migrations only go forward. An older image refuses a database a newer one migrated (*the database schema version … is newer than the version … this build supports*): to go back, restore the database backup taken before the upgrade, then run the older tag. - Stay on `:latest` (or a pinned `:`) in production. A container on `:nightly` runs unreleased code: move it to `:latest` by editing the image tag, after a backup. - Release notes list upgrade steps when a release needs one (a variable renamed, a template field added). Earlier compose files and templates set `CHRONOS_LOG_LEVEL: Information`, which now locks both log levels: delete the line to choose them in the admin panel. ## Backup and restore | Part | Holds | How | |---|---|---| | Archive (`/archive`) | Photos, sidecars, projects, proxies, renders, the trash | Your usual file backup (rsync, snapshots, Unraid's tools). Include every `.chronos` folder | | Database | The index, users and sign-ins, schedules, job history, audit log | `pg_dump` (below). The index part can also be rebuilt from the archive's sidecars (admin panel › Archive › *Rebuild*), the rest cannot | | `/data` | Settings, the TLS certificate and key, logs | Copy the folder | Back up (the server stopped, so nothing changes while the dump runs): ```sh docker compose stop chronos docker compose exec -T postgres pg_dump -U chronos -d chronos -Fc > chronos-$(date +%F).dump sudo tar -czf chronos-data-$(date +%F).tgz data docker compose start chronos ``` Restore into the same or a new host (the same image tag, or a newer one): ```sh docker compose down sudo tar -xzf chronos-data-.tgz # puts ./data back docker compose up -d postgres docker compose exec -T postgres pg_restore -U chronos -d chronos --clean --if-exists < chronos-.dump docker compose up -d ``` Put the archive back at the same `CHRONOS_ARCHIVE` path before the last step. After restoring an older database next to a newer archive, run Archive › *Scan* so the index catches up with what the archive holds. ## Troubleshooting | Symptom | Cause and fix | |---|---| | The Uploader or Chronos cannot connect | The client uses a port the host does not publish. Copy the **Client address** from Settings › Network and TLS; when host ports are not 8080/8443, set **Public HTTP port** and **Public HTTPS port** to them first ([Ports](#ports)) | | *Not a Chronos server* | Another service answers on that host port (on the owner's host 8443 is another service). Use the client address with the right public HTTPS port | | The free space shown is the cache's (Unraid) or too small | A cached share reports its primary storage. Map the share's array view read-only to `/space` and set `CHRONOS_SPACE_PATH=/space` ([unraid.md](unraid.md#free-space-of-the-array)) | | The container restarts at once, log: *… is not writable by PUID:PGID* | Give that user write access to the archive (or the named `.chronos` folder) on the host, or set `PUID`/`PGID` to its owner | | Log: *Database not reachable yet … retry* | PostgreSQL is starting, or `CHRONOS_DB_HOST` is wrong. Container names resolve only on a shared user-defined network; on Unraid's default bridge use the host's IP | | A field in the admin panel is read-only | A variable sets it; its tooltip names it. Remove the variable to change it in the panel | | The client asks to trust a new fingerprint | `/data` was replaced or the self-signed certificate was renewed. Compare with the admin panel before accepting | | Clients do not find the server by themselves | LAN discovery needs host networking; type the client address instead | | *Copy to videos folder* fails (`videos_folder_unset`, `videos_folder_invalid`) | Map a host folder outside the archive to `/videos` and set `CHRONOS_VIDEOS_PATH=/videos` | | `docker pull` asks for credentials | The organisation is private: `docker login gitea.encke-hake.ts.net` | | Host networking: the server does not start, port in use | Set `CHRONOS_HTTP_PORT` / `CHRONOS_HTTPS_PORT` to free ports | For a bug report attach the server's diagnostics zip (admin panel › Logs › *Diagnostics*): logs, a system report, the settings and recent failed jobs, never photos, passwords or tokens. You download it; it goes nowhere by itself.