Co-authored-by: Alberto Balbo <alberto.balbo.96@gmail.com>
15 KiB
Chronos
Chronos turns folders of photos (RAW, JPEG, HEIC…) into finished time-lapse videos and keeps a lifetime archive of your shoots organised, verified and searchable — on one PC or on a shared server.
This repository publishes the installers, the Docker image instructions, the Unraid template and the translations for community review. Development happens elsewhere; please use the issues here for bugs and translation fixes.
Components
| Program | Runs on | What it does |
|---|---|---|
| Chronos Desktop | Windows 10 21H2+ / 11, x64 | Desktop client: card import with hash verification, archive, analysis advisor, sequence editor, rendering with GPU encoders (H.264, HEVC, AV1); can share its library on the local network |
| Chronos Uploader | Windows 10 21H2+ / 11, x64 | Small tray program that uploads photos, folders, cards and watch folders to a Chronos Server or a shared library |
| Chronos Server | Docker (linux/amd64), Unraid | Shared archive, users, resumable uploads, sync, background jobs, render delegation to GPU-equipped PCs, web admin panel |
![]() |
![]() |
![]() |
![]() |
Requirements
- Desktop programs: Windows 10 version 21H2 or later, or Windows 11, 64-bit (x64). 8 GB of memory or more is recommended for 4K renders. No other runtime is needed: the programs are self-contained.
- Camera RAW files: Chronos develops DNG, CR2, NEF, ARW, PEF and RAF on its own. With Microsoft's free Raw Image Extension installed, Windows' decoder is used first and covers the other formats (CR3, ORF, RW2…); without it they render from the full-size preview embedded by the camera. HEIC needs Microsoft's HEIF Image Extensions and HEVC Video Extensions.
- Hardware encoding: any GPU whose driver provides Media Foundation encoders (NVIDIA, AMD, Intel). Without one, Chronos encodes H.264 in software and its own formats (AVI, GIF, APNG, image sequences).
- Server: Docker 20.10+ (or Unraid 6.12+) and PostgreSQL 16 or 17. On Windows, Chronos Desktop shares its own library instead (below).
Install, upgrade, uninstall (Windows)
- Download
Chronos-Setup-<version>.exe, the one setup for Chronos Desktop and Chronos Uploader, from the latest release. - Check the download (optional, recommended): in PowerShell run
Get-FileHash .\Chronos-Setup-<version>.exe -Algorithm SHA256and compare the value with the line for that file inSHA256SUMSof the same release. - Run the setup. It installs for the current user into
%LOCALAPPDATA%\Programs\Chronoswithout administrator rights; choose All users to install intoProgram Files(Windows asks for permission). Tick Chronos Desktop, Chronos Uploader or both; the Changes row lists what an update will do before it runs. Run it again later to add or remove a program; with nothing ticked it uninstalls. A Chronos Uploader 1.0 installed on its own is replaced by it, keeping its settings; a Chronos Server 1.0 for Windows is kept, marked No longer offered, until you untick it.
- Upgrade: Chronos Desktop and Chronos Uploader check this repository at start (you can turn this off in
Settings › Updates) and show a notice when a new version exists. Download fetches the setup, verifies it against
SHA256SUMSand shows it in Explorer; run it to upgrade in place. Your archive, settings and index are kept. - Uninstall: Windows Settings › Apps › Installed apps › Chronos › Uninstall. Your photos and archive are never
touched; the program data in
%LOCALAPPDATA%\Chronosis removed only if you tick the option to do so, and only the part no other installed Chronos program still uses. A Chronos Server 1.0 service of that folder is stopped and removed. - Silent install (IT deployment):
Chronos-Setup-<version>.exe /S [/DIR="D:\Apps\Chronos"] [/ALLUSERS] [/COMPONENTS=Desktop,Uploader] [/NODESKTOP] [/NOSTARTMENU] [/LANG=it]. Silent uninstall:"%LOCALAPPDATA%\Programs\Chronos\Uninstall Chronos.exe" /uninstall /S. - Portable:
Chronos-win-x64-portable-<version>.zipkeeps its data in adatafolder next toChronos.exe(because of theportable.txtfile). Do not unpack it into a OneDrive or Dropbox folder.
Chronos Server with Docker Compose
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 (folder of your archive), PUID/PGID, TZ
docker compose up -d
Create the archive folder owned by PUID:PGID first (for example mkdir -p <folder> && chown 1000:1000 <folder>). An
empty folder, or one owned by root (as Docker creates a missing one), 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.
Open http://<host>:8080/admin, sign in as admin with the password from .env and choose a new one. Chronos and
the Uploader connect to the Client address the admin panel shows under Settings › Network and TLS, by default
https://<host>:8443 (an address typed without a port means 8443; https://<name> alone means 443, a reverse proxy).
The first connection shows the server's certificate fingerprint, which the admin panel shows under Settings so you can
compare them. An address that answers but is not Chronos (another service on that port) is reported as such, and its
certificate is never offered for trust.
- Image:
gitea.encke-hake.ts.net/balbosoft/chronos-server:latest, the newest stable release (before the first one, the newest pre-release); also:<version>, and:nightly, the development version rebuilt every night, not for production use. Architecture:linux/amd64. If the registry asks you to sign in, rundocker login gitea.encke-hake.ts.netwith your Gitea account first. - Volumes:
/archive(originals, sidecars, proxies, renders — the archive stays readable without Chronos) and/data(settings, TLS certificate, uploads in progress, logs). - Free space: the admin panel shows the archive volume's, or with
CHRONOS_SPACE_PATHthat of another folder. An Unraid share (/mnt/user/<share>) reports its primary storage, often the cache, while the mover sends the photos to the array: map the share's array view read-only (/mnt/user0/<share>:/space:ro) and setCHRONOS_SPACE_PATH: /space. Uploads always check the archive volume itself (507when it is full). - Upgrade:
docker compose pull && docker compose up -d. Jobs in progress resume from their last checkpoint. - All settings: environment variables
CHRONOS_*(seedocker-compose.yml) or/data/server.json. Rundocker run --rm gitea.encke-hake.ts.net/balbosoft/chronos-server:latest --helpfor the list. - Logs:
/data/logs/server-yyyyMMdd.log, or one file per hour withCHRONOS_LOG_ROTATION=hourly(UTC). A file continues in.1.log,.2.log… at 50 MB (CHRONOS_LOG_MAX_FILE_MB), files are kept 14 days (CHRONOS_LOG_RETENTION_DAYS) and the oldest go when all of them pass 1024 MB (CHRONOS_LOG_MAX_TOTAL_MB; 0: no limit).CHRONOS_LOG_LEVELsets the level of the files and the console,CHRONOS_LOG_CONSOLE_LEVELthe console's alone. Without these variables the admin panel changes them in Settings › Logs while the server runs; a field a variable fixes is read-only there, and its tooltip names the variable. The compose file and Unraid template of earlier versions setCHRONOS_LOG_LEVEL: Information, which now fixes both levels: remove it (compose: delete the line; Unraid: edit the container and clear Log level) to choose them in the panel. - Other host ports: when you publish the container's ports as other host ports (
18443:8443), keep the container ports (8080 and 8443: in a container the admin panel shows them read-only) and enter the host ports as Public HTTP port and Public HTTPS port in Settings › Network and TLS, or setCHRONOS_PUBLIC_HTTP_PORTandCHRONOS_PUBLIC_HTTPS_PORT, which then lock them. They apply at once: the client address, the admin panel's redirect to HTTPS and LAN discovery name the ports clients can reach. - LAN discovery (
CHRONOS_DISCOVERY, on by default) needs host networking (network_mode: hostin compose, Network type Host on Unraid): on a bridge network its broadcasts never leave the container's network. Without it, type the client address in Chronos and in the Uploader. Withnetwork_mode: hostthe namepostgresno longer resolves: remove theportsof thechronosservice, publish PostgreSQL on loopback (ports: ["127.0.0.1:5432:5432"]underpostgres) and setCHRONOS_DB_HOST: 127.0.0.1. - With host networking the port mappings do nothing: the server listens on the host's 8080 and 8443 itself, and the
container does not start when another service already uses either. Then add the variable
CHRONOS_HTTP_PORTorCHRONOS_HTTPS_PORTwith a free port (compose: underenvironment; Unraid: Add another Path, Port, Variable… › Variable, KeyCHRONOS_HTTPS_PORT), and leave the public ports empty: clients reach the listening ports directly. - Behind a reverse proxy (
CHRONOS_TLS_MODE=proxy), only the proxies listed inCHRONOS_TRUSTED_PROXIESmay setX-Forwarded-*headers. By default that is loopback only: other machines on your network reach the HTTP port directly, so they must not choose the address the sign-in limit and the audit log see. List your proxy's own address. Give a proxy container a fixed IP on a user-defined Docker network it shares with Chronos (ipv4_addressin compose, Fixed IP address on Unraid), for example172.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): Docker relays connections to published ports from the gateway (IPv6 clients, the host itself), and on the default bridge every other container would count as your proxy too. For a proxy running on the Docker host itself, run Chronos withnetwork_mode: host: the proxy then reaches it over loopback. The admin panel shows Not via proxy when a page did not come through a trusted proxy over HTTPS.
Chronos Server on Unraid
- Install the official postgresql17 template from Community Applications. Create a database
chronosowned by a rolechronos(for example withdocker exec -it postgresql17 psql -U postgres -c "CREATE ROLE chronos LOGIN PASSWORD '…'" -c "CREATE DATABASE chronos OWNER chronos"). - Save the template
unraid/chronos.xmlon the Unraid server as/boot/config/plugins/dockerMan/templates-user/my-chronos-server.xml(for example withwget -O /boot/config/plugins/dockerMan/templates-user/my-chronos-server.xml <TemplateURL>, the address in the template's<TemplateURL>). Unraid's Template repositories read GitHub and GitLab addresses, not Gitea's. - Docker › Add container › Template
chronos-server. Set the admin password, the database host, password and the archive share (default/mnt/user/Timelapse). The database host is the Unraid server's IP address (the PostgreSQL template publishes port 5432): container names resolve only when both containers are on the same custom Docker network, not on the default bridge. If you change the HTTP or HTTPS port, enter the same port in Public HTTP port or Public HTTPS port (or later in the admin panel's Settings › Network and TLS). Array view is the same share under/mnt/user0(default/mnt/user0/Timelapse): the admin panel then shows the array's free space rather than the cache's. Change it with the archive share, or remove it and clear Space path. - Open the WebUI (
http://[IP]:8080/admin). Clients connect to the Client address in Settings › Network and TLS,https://[IP]:<HTTPS port>. On network type Bridge LAN discovery stays inside Docker, so clients do not find the server by themselves: type that address. Network type Host lets them find it; the server then listens on the host's own 8080 and 8443, so when another service uses either, add the variableCHRONOS_HTTP_PORTorCHRONOS_HTTPS_PORTfirst (see host networking above).
Upgrading a container made from an earlier template, or one on :nightly: edit the container, set Repository to
…/chronos-server:latest, and set Public HTTP port and Public HTTPS port to the host ports the template maps (for
example 8087 and 8444), or enter them in the admin panel. The ports the panel listed as HTTP and HTTPS port are the
container's (8080 and 8443), not the ones clients use.
The template file is unraid/chronos.xml.
Share a library from Chronos Desktop
There is no separate Chronos Server for Windows any more. In Chronos Desktop turn on Settings › Server › Share this library: while Chronos runs it serves this PC's archive to other PCs, Chronos Uploader and render nodes with the same engine as the Docker image, on HTTPS 8443 and HTTP 8080 by default. Server › This library shows the addresses and the certificate fingerprint to give to clients (each with Copy), the first admin's temporary password, the clients connected and Admin panel. Allow Chronos through the Windows firewall on private networks when Windows asks.
Moving from Chronos Server 1.0 for Windows: share the same archive folder from Chronos Desktop, or run the Docker image
with it; then untick Chronos Server in the setup, which removes it and its service. Its data in
C:\ProgramData\Chronos Server is kept.
Translations
Chronos is written in English and Italian; every other language is machine-translated and marked as such in
Settings › About. The source strings are in i18n/: en/<Area>.resx is the source, <language>/<Area>.<language>.resx
the translation. To suggest a correction, open a Translation review issue with the key, the current text and
your proposal — or the in-app Suggest a fix link in Settings › About, which leads here.
Verifying downloads
Every release carries SHA256SUMS. On Linux or macOS: sha256sum -c SHA256SUMS --ignore-missing. Chronos's
in-app update download performs the same check before showing the setup or portable zip. Signed builds carry an Authenticode
signature; unsigned builds may show a SmartScreen prompt.
Support and security
- Bugs: open a Bug report issue (attach the diagnostics bundle from Settings › Advanced › Diagnostics › Export bundle, or the server's from admin panel › Logs › Diagnostics; it contains logs and system information, never photos, passwords or tokens).
- Security problems: see SECURITY.md — please do not open public issues for them.
Licence
Chronos is proprietary software distributed free of charge under the End User Licence Agreement.




