Files
Chronos/docs/deploy/unraid.md
T
Alby96andClaude Opus 5.5 b4c2f5805b docs: deploy guide, owner review 4 request (phase 6)
Owner review 1 phase 6 asks for Docker, Unraid and deploy documentation. docs/deploy/
now covers the image tags, volumes, every CHRONOS_* variable with its default, ports and
public ports (the owner's host 8087/8444 mapping), TLS modes and the fingerprint,
upgrades and forward-only migrations, backup and restore, PostgreSQL, troubleshooting,
and the desktop Setup, portable mode and update channel.

The owner review 4 request (2026-11-06) is recorded with its interpretation and plan;
BRIEF §14.9 lists CHRONOS_TRUSTED_PROXIES, which the server already read, §19.6 points
to the Unraid guide, and §24 gains the rows of owner review 4 and phase 6. STATUS shows
both in progress for v0.1.0-rc.14, then v1.0.0.

Refs #22

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

8.0 KiB
Raw Blame History

Chronos Server on Unraid

Chronos Server from the template deploy/unraid/chronos.xml, next to the official PostgreSQL template. Every variable and behaviour is described in docker.md; this page covers what is particular to Unraid.

Install

  1. PostgreSQL. Install the official postgresql17 template from Community Applications (16 works too). Create a role and a database for Chronos:

    docker exec -it postgresql17 psql -U postgres \
      -c "CREATE ROLE chronos LOGIN PASSWORD '<a long random password>'" \
      -c "CREATE DATABASE chronos OWNER chronos"
    
  2. The template. Unraid's Template repositories read GitHub and GitLab addresses, not Gitea's, so save the template as a user template from the Unraid terminal:

    wget -O /boot/config/plugins/dockerMan/templates-user/my-chronos-server.xml \
      https://gitea.encke-hake.ts.net/BalboSoft/Chronos/raw/branch/main/deploy/unraid/chronos.xml
    

    While the BalboSoft organisation is private, the download and the image pull need an account: download the file in a signed-in browser and copy it there, and run docker login gitea.encke-hake.ts.net once in the terminal.

  3. The container. Docker › Add container › Template › chronos-server. Fill in at least:

    Field Value
    Admin password The first password of admin; a change is required at the first sign-in
    Database host The Unraid server's IP address (the PostgreSQL template publishes 5432). A container name resolves only when both containers are on the same custom Docker network, never on the default bridge
    Database password The role's password from step 1
    Archive The share of your time-lapses, default /mnt/user/Timelapse
    Array view The same share under /mnt/user0, default /mnt/user0/Timelapse (see free space)

    Leave the network type on Bridge unless you need LAN discovery (below).

  4. First sign-in. Open the WebUI (http://[IP]:[HTTP port]/admin), sign in as admin and choose a new password.

  5. Clients. In Settings › Network and TLS copy the Client address into Chronos and the Uploader and compare the Fingerprint at their first connection.

Template fields

Field Container side Default Notes
HTTP port port 8080 8080 Admin panel and API over HTTP; the WebUI link follows it
HTTPS port port 8443 8443 API over TLS for Chronos and the Uploader
Public HTTP port CHRONOS_PUBLIC_HTTP_PORT empty The HTTP port above when it is not 8080
Public HTTPS port CHRONOS_PUBLIC_HTTPS_PORT empty The HTTPS port above when it is not 8443: the port of the client address
Archive /archive /mnt/user/Timelapse Originals, sidecars, proxies, renders
Array view /space (read-only) /mnt/user0/Timelapse Optional; with Space path
Videos /videos empty Optional folder for Copy to videos folder, not inside the archive (for example /mnt/user/Videos/Chronos); with Videos path
App data /data /mnt/user/appdata/chronos Settings, TLS certificate, uploads in progress, logs
Admin user / Admin password CHRONOS_ADMIN_USER / CHRONOS_ADMIN_PASSWORD admin / empty Read only while no administrator exists
Database host, port, name, user, password, TLS CHRONOS_DB_* —, 5432, chronos, chronos, —, prefer Port and TLS are advanced
Videos path CHRONOS_VIDEOS_PATH empty /videos once Videos is mapped; empty turns copying off unless a folder is set in the admin panel
TLS mode, Trusted proxies, Space path, Server name, Parallelism, Priority queue, the log fields, Audit retention, Diagnostics log size, PUID (99), PGID (100), Time zone the variables of docker.md as there Advanced. Empty means the admin panel chooses; a value locks the setting there

The template has no field for CHRONOS_TLS_CERT, CHRONOS_TLS_KEY, CHRONOS_LANG, CHRONOS_DISCOVERY, CHRONOS_HTTP_PORT or CHRONOS_HTTPS_PORT: add them with Add another Path, Port, Variable… › Variable when needed.

Ports other than 8080 and 8443

When another container already uses 8080 or 8443 on the Unraid host, change only the host side and tell Chronos which ports clients use. The owner's setup:

Field Value
HTTP port 8087 (container 8080)
HTTPS port 8444 (container 8443)
Public HTTP port 8087
Public HTTPS port 8444

Clients then connect to https://<Unraid IP>:8444, the client address the admin panel shows, and the WebUI opens http://<Unraid IP>:8087/admin. The admin panel's HTTP port and HTTPS port stay 8080 and 8443, read-only: they are the container's ports, not the ones clients use. The public ports may be left empty in the template and entered in the admin panel's Settings › Network and TLS instead; set in the template, they are locked there.

Free space of the array

A user share (/mnt/user/<share>) reports the free space of its primary storage, often the cache, while the mover sends the photos to the array. The Array view maps the same share as seen on the array alone (/mnt/user0/<share>) read-only to /space, and Space path /space makes the admin panel show that volume's free space. When the archive's own volume differs it shows apart as Write volume. Change Array view together with Archive, or remove it and clear Space path. Uploads still check the archive's own volume.

Network type

  • Bridge (default): the port mappings apply, LAN discovery stays inside Docker, clients type the client address.
  • Host: clients find the server by themselves, the mappings are ignored and the server listens on the host's 8080 and 8443 itself; it does not start when another service uses either. Add the variable CHRONOS_HTTP_PORT or CHRONOS_HTTPS_PORT with a free port first and leave the public ports empty.
  • A custom Docker network shared with the PostgreSQL container lets Database host be the container's name.

Upgrading

  1. Back up /mnt/user/appdata/chronos and the database (below).
  2. Docker › the container › Check for updates / Update, or Force update. The database is migrated at start; jobs resume from their last checkpoint.

A container made from an earlier template, or one on :nightly: edit it, set Repository to gitea.encke-hake.ts.net/balbosoft/chronos-server:latest, and when its host ports are not 8080/8443 add the public ports (Public HTTP port 8087 and Public HTTPS port 8444 in the owner's case), or enter them in the admin panel. An earlier template's Log level Information now locks both log levels: clear it to choose them in the admin panel. Going back to an older tag needs the database backup taken before the upgrade (migrations only go forward).

Backup

  • App data and PostgreSQL: the Appdata Backup plugin, with both containers stopped during the backup, covers /mnt/user/appdata/chronos and the PostgreSQL template's data folder. Or dump the database yourself: docker exec postgresql17 pg_dump -U chronos -d chronos -Fc > /mnt/user/backups/chronos-$(date +%F).dump.
  • Archive: the share itself, with your usual share backup; include the .chronos folders.
  • Restore: put the app data and the archive back, recreate the container from the template with the same paths, restore the dump (docker exec -i postgresql17 pg_restore -U chronos -d chronos --clean --if-exists < <dump>), then start Chronos. See docker.md › Backup and restore for what each part holds.

Troubleshooting

See docker.md › Troubleshooting. The two Unraid classics:

  • The Uploader cannot connect: the host ports differ from 8080/8443 and the public ports are empty, so the client address names ports the host does not publish. Set Public HTTP port and Public HTTPS port.
  • The free space shown is the cache's: map Array view and set Space path /space.