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>
20 KiB
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
- 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 toPUID:PGIDat start: the folder itself, never its contents. Any other folder that user cannot write stops the container with a one-line error naming it. - Open
http://<host>:8080/admin, sign in asadminwithCHRONOS_ADMIN_PASSWORDand choose a new password (a change is required at the first sign-in). WithoutCHRONOS_ADMIN_PASSWORDthe 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. - 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 |
/archiveand/dataare image volumes;/videosand/spaceare not, so an image run without them makes no anonymous volume. A/videosthat is not a mounted volume, or thatPUID:PGIDcannot 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. RemoveCHRONOS_VIDEOS_PATHand the volume to turn copying off. - The server writes into the archive's
.chronosfolders 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 withchown -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/withlocks,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/healthreports archive "incomplete" until it can be made. Both check again by themselves (the dashboard at each read,/healthwhen 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/healthreports 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.localalone 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_PORTto free ports and leave the public ports empty. The namepostgresno longer resolves there: publish PostgreSQL on loopback (ports: ["127.0.0.1:5432:5432"]underpostgres) and setCHRONOS_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
/datais lost or the self-signed certificate is renewed: clients then ask again. Compare before accepting; keep/datain 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_PROXIESmay setX-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_addressin 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
- Back up first: at least the database and
/data(below). docker compose pull && docker compose up -d.- 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:nightlyruns unreleased code: move it to:latestby 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.