Files
Chronos/docs/deploy/docker.md
T
Alby96andClaude Opus 5.5 2c15ee0e09 fix: address the rc.14 review
Settings no longer makes a folder an archive on its own: a typed or
picked folder without archive.json is made one only after a
confirmation naming it, and Settings > Import keeps this PC's archive
folder and never creates one. A half-typed path or another PC's drive
letter could otherwise get .chronos and sidecars written unasked.

The server's structure check creates nothing in a root that lost its
archive.json (an unmounted disk's empty mount point) and reports it
unavailable; /health re-checks when its last check is over 10 s old,
so a fix on the host shows without a dashboard read.

The admin board reads the server newest first with Order off, counts
Published over the server's total, and a Shift range runs along the
lane picked in. Admin sizes keep number and unit together. A sent
workspace render whose file left exports/ is no longer listed as
missing. Desktop Board cards put their actions under the text while
the player is open. Start-up range errors name the CHRONOS_* variable;
the deploy guide documents the parallelism clamp and the log rule.

Refs #29 #31

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 17:52:44 +01:00

20 KiB
Raw Blame History

Chronos Server with Docker

Chronos Server in a container next to PostgreSQL 17, from deploy/docker/docker-compose.yml. For Unraid see unraid.md; the settings below are the same there.

Install

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://<host>: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://<host>: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
:<version> (: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.<run>); 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 <PUID>:<PGID> <archive>/.chronos. Nothing inside the archive is ever chowned by the container.
  • At every start the server lays out the archive's folder tree inside /archive (.chronos/ with locks, journal, staging, trash, trash/photos, trash/videos), making only the missing folders and touching nothing that exists. A folder it cannot make does not stop the start: the log warns, the dashboard shows Archive incomplete (the folder and reason in its tooltip) and /health reports archive "incomplete" until it can be made. Both check again by themselves (the dashboard at each read, /health when its last check is over 10 seconds old), so a fix on the host needs no restart. A root without its .chronos/archive.json (an unmounted disk leaves an empty mount point) gets no folders: the dashboard shows Archive incomplete and /health reports archive "missing".

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, except CHRONOS_PARALLELISM, which is held to 1–64. The logs' total (CHRONOS_LOG_MAX_TOTAL_MB) may not be below the log file size (CHRONOS_LOG_MAX_FILE_MB), unless it is 0.

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
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://<host>: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://<host>:8444; admin panel http://<host>:8087/admin
Host networking (network_mode: host) none (ignored) leave empty https://<host>: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://<proxy name>
  • 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).
  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 :<version>) 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):

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):

docker compose down
sudo tar -xzf chronos-data-<date>.tgz           # puts ./data back
docker compose up -d postgres
docker compose exec -T postgres pg_restore -U chronos -d chronos --clean --if-exists < chronos-<date>.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)
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)
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
Dashboard: Archive incomplete; /health: archive "incomplete" A folder of the archive's tree cannot be made (share unavailable, permission denied, read-only, a file in the way; the tooltip names it). Fix it on the host; the next dashboard read, or /health within 10 seconds, checks again, no restart needed
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.