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>
238 lines
20 KiB
Markdown
238 lines
20 KiB
Markdown
# 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://<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](#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](#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 `:<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):
|
||
|
||
```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-<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](#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 |
|
||
| 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.
|