feat: single setup, mass-pass progress, per-server homes, Desktop shares its library (owner review 5, v1.1.0) (#68)
CI / Build and test (push) Successful in 11m36s
CI / Windows tests and installer (push) Skipped
CI / YAML check (push) Successful in 12s
Release / Build, test and publish (push) Successful in 14m56s
CI / PostgreSQL 16 integration (push) Successful in 10m11s
CI / PostgreSQL 17 integration (push) Successful in 10m15s
CI / Docker image (push) Successful in 45s
Release / Server image (push) Successful in 4m55s

Co-authored-by: Alberto Balbo <alberto.balbo.96@gmail.com>
This commit was merged in pull request #68.
This commit is contained in:
Alby96 authored and Alby96 committed 2026-11-15 18:11:43 +01:00
1 parent 988068ee8e
commit 20d64af4a4
793 files changed
+23882 -2096

No files matched your search

+8 -5
View File
@@ -8,7 +8,7 @@ specification behind each behaviour is `docs/BRIEF.md` (§14.9 configuration and
|---|---|
| [docker.md](docker.md) | Chronos Server in Docker with Compose: image tags, volumes, every `CHRONOS_*` variable, ports, TLS, PostgreSQL, upgrades, backup and restore, troubleshooting |
| [unraid.md](unraid.md) | Chronos Server on Unraid with the template `deploy/unraid/chronos.xml` and the official PostgreSQL template, including host ports other than 8080/8443 |
| [desktop.md](desktop.md) | Chronos and Chronos Uploader on Windows: Setup, portable mode, updates, uninstall; Chronos Server on Windows |
| [desktop.md](desktop.md) | Chronos Desktop and Chronos Uploader on Windows: the one setup, portable mode, updates, uninstall; sharing a library from Chronos Desktop |
The short user guide that ships with every release is `deploy/releases-repo/README.md` (it becomes the README of a
separate releases repository when `RELEASES_REPO` is set). It and these guides say the same things; these go further.
@@ -17,9 +17,12 @@ separate releases repository when `RELEASES_REPO` is set). It and these guides s
| Program | Runs on | Talks to |
|---|---|---|
| **Chronos** (desktop) | Windows 10 21H2+ / 11, x64 | Its own archive and index on the PC; optionally a Chronos Server over HTTPS |
| **Chronos Uploader** | Windows 10 21H2+ / 11, x64 | A Chronos Server over HTTPS |
| **Chronos Server** | Docker (`linux/amd64`), Unraid 6.12+, Windows 10/11/Server 2019+ x64 | PostgreSQL 16 or 17 (Linux), SQLite or PostgreSQL (Windows); its archive folder |
| **Chronos Desktop** | Windows 10 21H2+ / 11, x64 | Its own archive and index on the PC; optionally a Chronos Server over HTTPS; can share its own library on the LAN (Settings › Server › *Share this library*) |
| **Chronos Uploader** | Windows 10 21H2+ / 11, x64 | A Chronos Server, or a library Chronos Desktop shares, over HTTPS |
| **Chronos Server** | Docker (`linux/amd64`), Unraid 6.12+ | PostgreSQL 16 or 17; its archive folder |
On Windows there is no separate server program: Chronos Desktop › Settings › Server › *Share this library* serves the
PC's library with the same engine ([desktop.md](desktop.md#share-a-library-from-chronos-desktop)).
The archive is the source of truth: photos, sidecars, proxies and renders live in ordinary folders, and the database is
an index that can be rebuilt from them (BRIEF §7). Users, sign-ins, schedules, job history and the audit log live only
@@ -29,7 +32,7 @@ in the database, so back up both (see [docker.md › Backup and restore](docker.
| What | Where |
|---|---|
| Windows installers, portable zips, the Windows server zip, `SHA256SUMS` | Releases of `BalboSoft/Chronos` on `https://gitea.encke-hake.ts.net` (or of the releases repository) |
| The setup (`Chronos-Setup-<version>.exe`), the portable zip, `SHA256SUMS` | Releases of `BalboSoft/Chronos` on `https://gitea.encke-hake.ts.net` (or of the releases repository) |
| Server image | `gitea.encke-hake.ts.net/balbosoft/chronos-server` — `:latest`, `:<version>`, `:nightly` |
| Compose file and `.env` example | `https://gitea.encke-hake.ts.net/BalboSoft/Chronos/raw/branch/main/deploy/docker/docker-compose.yml` and `…/deploy/docker/.env.example` |
| Unraid template | `https://gitea.encke-hake.ts.net/BalboSoft/Chronos/raw/branch/main/deploy/unraid/chronos.xml` |
+51 -29
View File
@@ -1,7 +1,9 @@
# Chronos on Windows
Chronos (the desktop program), Chronos Uploader and Chronos Server for Windows. Requirements: Windows 10 21H2 or later,
or Windows 11, x64; 8 GB of memory or more for 4K renders. The programs are self-contained: no .NET runtime to install.
Chronos Desktop and Chronos Uploader, and sharing a library from Chronos Desktop. Requirements: Windows 10 21H2 or
later, or Windows 11, x64; 8 GB of memory or more for 4K renders. The programs are self-contained: no .NET runtime to
install. Chronos Server itself runs only in Docker ([docker.md](docker.md), [unraid.md](unraid.md)); on Windows, Chronos
Desktop serves its own library instead (below).
## Downloads
@@ -9,12 +11,14 @@ Each release on Gitea carries:
| File | What it is |
|---|---|
| `Chronos-Setup-<version>.exe` | Setup with the components Chronos, Uploader and, optionally, Server |
| `Chronos-Uploader-Setup-<version>.exe` | Setup of the Uploader alone |
| `Chronos-win-x64-portable-<version>.zip` | Chronos without installing (portable mode) |
| `Chronos-Server-win-x64-<version>.zip` | Chronos Server for Windows without the setup |
| `Chronos-Setup-<version>.exe` | The one setup: Chronos Desktop, Chronos Uploader or both |
| `Chronos-win-x64-portable-<version>.zip` | Chronos Desktop without installing (portable mode) |
| `SHA256SUMS` | The SHA-256 of every file |
Since 1.1 there is no separate Uploader setup and no Chronos Server for Windows. If you installed Chronos Uploader 1.0
on its own, run `Chronos-Setup-<version>.exe` once: it replaces the separate Uploader, keeping its sign-in entry, its
shortcut and its data.
Check a download before running it: `Get-FileHash .\Chronos-Setup-<version>.exe -Algorithm SHA256` in PowerShell, then
compare with its line in `SHA256SUMS`. Signed builds carry an Authenticode signature; unsigned ones may show a
SmartScreen prompt.
@@ -22,17 +26,24 @@ SmartScreen prompt.
## Setup
- **Per user** (default, no administrator rights): `%LOCALAPPDATA%\Programs\Chronos`.
- **All users**: `Program Files` (Windows asks for permission). Choosing the *Server* component installs for all users,
since it runs as a Windows service.
- Options: components, folder, desktop and Start menu shortcuts, the `.chronos` file type.
- **All users**: `Program Files` (Windows asks for permission).
- Options: components (Chronos Desktop, preselected, and Chronos Uploader), folder, desktop and Start menu shortcuts,
the `.chronos` file type.
- **Silent** (IT deployment): `Chronos-Setup-<version>.exe /S [/DIR="D:\Apps\Chronos"] [/ALLUSERS]
[/COMPONENTS=Chronos,Uploader,Server] [/NODESKTOP] [/NOSTARTMENU] [/LANG=it]`.
- **Upgrade**: run the newer setup over the installed version; it upgrades in place and keeps archive, settings and
index.
[/COMPONENTS=Desktop,Uploader] [/NODESKTOP] [/NOSTARTMENU] [/LANG=it]`. `Desktop` and `Chronos` name the same
component. An explicit `/COMPONENTS` list is exact: an installed component it leaves out is removed.
- **Upgrade, add or remove**: run the newer setup over the installed version; it upgrades in place and keeps archive,
settings and index. Tick or untick a program to add or remove it; the *Changes* row lists what will happen before
anything runs. A file you changed since the setup installed it is never deleted ("N changed files kept"). With every
program unticked the button becomes *Uninstall*.
- **Chronos Server 1.0 for Windows**: a setup that finds it shows "Chronos Server 1.0.0 · No longer offered" and leaves
it, and its Windows service, untouched. Untick it (or leave it out of `/COMPONENTS`) to remove it with its service; its
data in `%ProgramData%\Chronos Server` is kept. To keep serving that library, share it from Chronos Desktop (below) or
move to [Docker](docker.md).
- **Uninstall**: Windows Settings › Apps › Installed apps › Chronos › Uninstall, or silently
`"%LOCALAPPDATA%\Programs\Chronos\Uninstall Chronos.exe" /uninstall /S`. Photos and archives are never touched. The
program data in `%LOCALAPPDATA%\Chronos` goes only when you tick that option, and only the part no other installed
Chronos program still uses; a Chronos Server service of that folder is stopped and removed.
Chronos program still uses; a Chronos Server 1.0 service of that folder is stopped and removed.
## Data folders
@@ -44,6 +55,12 @@ SmartScreen prompt.
Keep neither inside a OneDrive or Dropbox folder: a SQLite index in a synced folder gets corrupted. The archive and
the workspace are folders you choose in Settings › Archive and Settings › Workspace (the workspace best on a fast local
disk).
Since 1.1 the workspace and the cache keep a separate home for this PC (`local\`) and for each server
(`servers\<id>\`); the first start of 1.1 sorts a 1.0 workspace and cache into them by renaming folders (a toast says
*Folders sorted*). Chronos 1.0 cannot open a sorted workspace: downgrading is not supported. Originals downloaded from a
server go to that server's own archive beside this PC's (for example `D:\ChronosArchive - Studio NAS`); Settings ›
Workspace › Home folders and Settings › Server › Known servers show every folder with *Open*.
Backups of the index go to `backups\` next to it every day (Settings › Advanced › *Back up now* for one more copy;
restore there too).
@@ -59,6 +76,8 @@ To upgrade, unpack the newer zip over it (or let *Download* fetch it, below); `d
repository and shows a one-line notice when a newer version exists. *Check for updates* asks at any time.
- *Download* fetches the setup (or, in portable mode, the portable zip), checks it against `SHA256SUMS` and shows it in
Explorer: run it to upgrade.
- Chronos Uploader checks the same way (its Settings › Updates: *Check on start*, *Check now*, *Download*, *Show setup*),
except at start when Chronos Desktop is installed in the same folder, whose notice covers the same setup.
- There is one channel: stable releases. Pre-releases (`-rc.N`) are never offered; install them by hand from the
Releases page. A pre-release build is offered every newer stable release, and the final release of its own version
once it is out (a `1.1.0-rc.1` build is offered `1.1.0`).
@@ -73,21 +92,24 @@ certificate fingerprint: compare it with the admin panel's and accept it once; a
that answers as another service is reported as *not a Chronos server*. Server setup and ports: [docker.md](docker.md),
[unraid.md](unraid.md).
## Chronos Server on Windows
## Share a library from Chronos Desktop
Choose the *Server* component in the setup, or unpack `Chronos-Server-win-x64-<version>.zip` into a folder under
`Program Files`.
On Windows a library is served by Chronos Desktop itself: Settings › Server › *Share this library*. While Chronos runs
it serves this PC's current archive to other PCs, Chronos Uploader and render nodes with the same engine as the Docker
image (API, admin panel, accounts, TLS, LAN announcement, uploads, sync, render nodes), over the desktop's own index:
there is no second copy of the data.
- Database: SQLite in `C:\ProgramData\Chronos Server` by default, or PostgreSQL with `CHRONOS_DB=postgres` and the
`CHRONOS_DB_*` variables ([docker.md](docker.md#environment-variables)); archive `C:\ChronosArchive` unless
`CHRONOS_ARCHIVE_PATH` says otherwise. The listening ports are 8080 and 8443 and can be changed in the admin panel.
- Run `Chronos.Server.exe` in a console, or as a service from an administrator prompt: `Chronos.Server.exe
--install-service` (remove with `--uninstall-service`). The service runs as LocalSystem and registers only from a copy
that only administrators can change.
- Without `CHRONOS_ADMIN_PASSWORD` the first start writes a temporary password to `initial-admin-password.txt` in the
data folder (open it from an administrator prompt).
- The data folder is readable only by the server's account, SYSTEM and Administrators. A console run that was not
elevated creates it as your account, and the service then refuses it and names that account: the user guide
(`deploy/releases-repo/README.md` › Chronos Server on Windows) gives the `takeown` and `icacls` commands that fix it.
- Index backups: the `index-backup` schedule copies the SQLite index daily at 03:00 (three copies kept). With
PostgreSQL use `pg_dump`.
- Ports: HTTPS 8443 and HTTP 8080 by default (Settings › Server › Sharing, with the public ports and the LAN
announcement). Windows may ask once to let Chronos through the firewall on private networks: allow it, or clients
cannot connect.
- Server › This library shows the addresses (with *Copy*), the ports, the certificate fingerprint (with *Copy*), the
first admin's temporary password while it has not been changed (*Show*, *Copy*), the clients of the last 5 minutes and
the render nodes online, and *Admin panel*. Clients connect exactly as to a Docker server ("studio-pc" alone works).
- Sharing stops when Chronos closes. A port in use leaves sharing *Not started*, naming the port.
- The server's own data (certificate, `server.json`, uploads) lives in `<data folder>\server`; accounts live in the
index, so its backups cover them.
- The settings Chronos Desktop owns read "Set in Chronos Desktop" in the admin panel.
Moving from Chronos Server 1.0 for Windows: share the same archive folder from Chronos Desktop (Settings › Archive, then
*Share this library*), or run the Docker image with that archive and a PostgreSQL database; then untick Chronos Server in
the setup. The 1.0 server's accounts and history stay in its own database in `%ProgramData%\Chronos Server`.
+6 -1
View File
@@ -76,7 +76,7 @@ with a message naming the variable, except `CHRONOS_PARALLELISM`, which is held
| Variable | Default | Meaning |
|---|---|---|
| `CHRONOS_DATA_PATH` | `/data` (Windows: `C:\ProgramData\Chronos Server`) | Data folder; read before `server.json`, which lives in it |
| `CHRONOS_DATA_PATH` | `/data` (Chronos Server 1.0 for 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 |
@@ -194,6 +194,11 @@ or `verify-full`. Or give a whole connection string in `CHRONOS_DB`.
| 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 |
The server's id (since 1.1, the app setting `server.id` in the database, announced to clients as `serverId`) travels
with the database: a restore keeps it, so desktops still know the server; a fresh database makes a new id. Never run
two servers from copies of one database: desktops would take them for one server (they warn when a known id comes
back with another certificate and another name).
Back up (the server stopped, so nothing changes while the dump runs):
```sh