Mass passes need to say what they do now (photo x of y, sequence n of m) without slowing down. This adds the contract and the engine side; handlers and displays follow in their own parcels. - Core: JobDetail (step, item, item x of y, part n of m with unit), JobStep and JobPartUnit appended-only and stored by kebab name; Job.Detail. - Protocol: JobDetailDto, appended as JobDto.Detail, JobProgressEvent.Detail and NodeProgress.Detail, so older peers ignore it and newer ones fall back. - Data: JobContext keeps a detail across reports (ReportAsync with a detail, ReportItemAsync without allocating, CheckpointAsync with a detail) and publishes at most once per ProgressInterval (500 ms on the engine's TimeProvider), at once for the first report, a new step or a completed count; a dropped report costs no allocation or lock, and the persist that falls due publishes what it saves. Persist stays at most every 5 s. JobWire maps steps, units and details; an unknown name reads as none. - Migration 0011 adds jobs.progress_detail (nullable JSON text); an unreadable cell reads as no detail. Lists return it. - Server: ProgressGate (500 ms per job, step-change and completion bypass) shared by the engine host and render nodes; node details are stored and broadcast, an older node without one still works. Refs #65 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Chronos (development repository)
Time-lapse ecosystem: Chronos (Windows desktop client), Chronos Server (Linux/Docker and Windows) and
Chronos Uploader (Windows), sharing one C#/.NET 10 engine with zero third-party packages. This repository is
BalboSoft/Chronos on the owner's Gitea (https://gitea.encke-hake.ts.net/BalboSoft/Chronos); users get the releases,
the server image and the Unraid template from it too (see Visibility).
- User guide (install, update, Docker, Unraid, verifying downloads):
deploy/releases-repo/README.md - Deploy guide (every variable, ports, TLS, upgrades, backup, troubleshooting):
docs/deploy/ - Specification:
docs/BRIEF.md· working rules:CLAUDE.md - Architecture and conventions:
docs/ARCHITECTURE.md· decisions:docs/DECISIONS.md· status:docs/STATUS.md· changes:docs/CHANGELOG.md - Visual design:
docs/ui/DESIGN.mdanddocs/ui/mockups/
Build, test, run
Requirements: the .NET SDK pinned in global.json. Windows builds and runs everything; Linux builds everything
(the Windows projects for compile checking) and runs Core, Data, Protocol, Server and Tools.
dotnet build Chronos.slnx -c Release
# Tests (one program per area; --filter text|category:name, --junit file, --verbose)
dotnet run --project tests/Chronos.Core.Tests -c Release -- --junit out/core.xml
dotnet run --project tests/Chronos.Data.Tests -c Release
dotnet run --project tests/Chronos.Server.Tests -c Release
dotnet run --project tests/Chronos.Tools.Tests -c Release
dotnet run --project tests/Chronos.Core.Windows.Tests -c Release # Windows
dotnet run --project tests/Chronos.App.Tests -c Release # Windows
# PostgreSQL integration tests (16 or 17); the MD5, cleartext, trust and TLS tests also read CHRONOS_TEST_PG_MD5,
# _CLEARTEXT, _TRUST, _TLS=1 and _ROOT_CERT. postgres-ci prepares a throw-away server for them through SQL as a
# superuser (it rewrites pg_hba.conf and turns TLS on): roles and passwords as in .gitea/workflows/ci.yml, the
# certificate for _ROOT_CERT in out/pg-tls/server.crt
export CHRONOS_TEST_PG="Host=127.0.0.1;Port=5432;Database=chronos_test;Username=chronos;Password=…;SslMode=disable"
dotnet run --project src/Chronos.Tools -- postgres-ci --connection "$CHRONOS_TEST_PG" --host localhost --certificates out/pg-tls
dotnet run --project tests/Chronos.Data.Tests -c Release
# Performance gates (500,000-photo library, 100,000-frame rebuild; minutes)
CHRONOS_PERF=1 dotnet run --project tests/Chronos.Data.Tests -c Release -- --filter category:perf --verbose
# Checks run by CI
dotnet run --project src/Chronos.Tools -- package-guard
dotnet run --project src/Chronos.Tools -- i18n check
dotnet run --project src/Chronos.Tools -- xaml-lint
dotnet format whitespace Chronos.slnx --verify-no-changes
dotnet run --project src/Chronos.Tools -- screenshots diff out/screenshots # Windows, after --capture (tests/visual/baselines/README.md)
# CC0 RAW samples for the decoder tests (tests/fixtures/manifest.json explains how to fill in URLs)
dotnet run --project src/Chronos.Tools -- fixtures
Run:
dotnet run --project src/Chronos.Server # admin panel https://localhost:8443/admin
src/Chronos.App/bin/Release/net10.0-windows/Chronos.exe [--capture <folder>]
src/Chronos.Uploader/bin/Release/net10.0-windows/Chronos.Uploader.exe
docker compose -f deploy/docker/docker-compose.yml up -d
The server reads /data/server.json (CHRONOS_DATA_PATH) and CHRONOS_* environment variables;
Chronos.Server --help lists them. On Linux it needs PostgreSQL; on Windows it defaults to SQLite.
Debug in VS Code (Windows)
Open the repository folder with the C# extension (.vscode/extensions.json recommends it), pick a configuration in
Run and Debug and press F5. Each launch configuration builds in Debug first (.vscode/tasks.json).
| Configuration | Starts |
|---|---|
| Chronos, Chronos Uploader | The desktop programs, with their usual data folder (%LOCALAPPDATA%\Chronos) |
| Chronos Server | The server on SQLite, ports 8080 and 8443, data and archive in out/debug/server; then opens the admin panel |
| … (screenshots) | --capture out/screenshots of Chronos, the Uploader or Setup |
| Chronos.Tools | The command line it asks for (i18n check by default) |
| Tests | The test program and runner options it asks for (--filter, --parallel 1, …), after building the solution |
| Attach to process | Nothing: attaches to a running process picked from a list |
- Sessions run side by side: start the next one with the green Start button in Run and Debug once the previous build has finished (F5 starts a session only when none runs). Tests rebuilds the programs too, so stop their sessions first when the code has changed.
- Quit an installed Chronos or Uploader first: a second copy hands over to it and ends. Debugging the Uploader points an existing Start with Windows entry at the Debug build. Closing the Uploader's window keeps it in the tray (the default): end its session with Stop.
- Stop the Docker stack or an installed Chronos Server before Chronos Server, which needs the same ports. The browser
warns about the server's self-signed certificate; sign in as
adminwith the temporary password inout/debug/server/data/initial-admin-password.txt. - Chronos, the Uploader and Setup log to files (
%LOCALAPPDATA%\Chronos\logs,%TEMP%\Chronos Setup); the server logs to the Debug Console. Windows Firewall asks about Chronos, the Uploader and the server at their first start. - VS Code passes the drive letter in lower case: the first build after one made with an upper-case drive letter (another terminal, Visual Studio) restores and recompiles everything.
CI
The workflows in .gitea/workflows run on Gitea Actions: one act_runner in Docker mode (label ubuntu-latest) on the
Linux server that also hosts Gitea, one job at a time. The .NET jobs run in the mcr.microsoft.com/dotnet/sdk:10.0
container and check out with plain git (the image has no Node.js, so no JavaScript actions such as
actions/checkout); the jobs that build images use the runner's own image and the host's Docker daemon. Nothing is
uploaded as an artifact or cached, and builds use 4 cores (BUILD_CPUS) so the host keeps memory for Gitea. Gitea
shows no job summary and no annotations: ::warning/::error lines appear in the log only.
| Workflow | When | What |
|---|---|---|
.gitea/workflows/ci.yml |
push to main, pull requests, manual |
Job build: build (warnings are errors), package guard, i18n check, XAML lint, format check, CC0 fixtures (a warning per missing sample), Core, Data (SQLite), Server and Tools tests, the Windows programs (App, Uploader, Setup) cross-compiled for win-x64, pack-installer and Chronos.Tools pe-check. postgres: PostgreSQL 16/17 service containers (host postgres, prepared by Chronos.Tools postgres-ci) for the integration tests (SCRAM, MD5, cleartext, trust, TLS). docker: the image built with the host's daemon and its /health smoke test with PostgreSQL 17 on a network of the run. yaml: workflows, issue forms in .gitea/ISSUE_TEMPLATE and the compose file (ruby:3.3-alpine, sources from Gitea's archive API). windows, only with WINDOWS_RUNNER: Core.Windows and App tests, screenshots (--capture) and their pixel diff against tests/visual/baselines, installer test (install, run, upgrade in place, uninstall) |
.gitea/workflows/docker.yml |
daily at 02:17 (main only), manual |
gitea.encke-hake.ts.net/balbosoft/chronos-server:nightly (linux/amd64; needs REGISTRY_TOKEN) |
.gitea/workflows/perf.yml |
weekly, manual | Performance gates on SQLite and PostgreSQL 17 (service container); timings printed at the end of the log |
.gitea/workflows/release.yml |
tag v*, manual re-publish |
The release (below) |
Windows-only tests without a Windows runner
Until WINDOWS_RUNNER names a Windows runner, CI skips the windows job: run its steps on a Windows PC before a
merge, from the repository root in PowerShell 7.
dotnet build Chronos.slnx -c Release
dotnet run --project tests/Chronos.Core.Windows.Tests -c Release --no-build
dotnet run --project tests/Chronos.App.Tests -c Release --no-build
# Screenshots and their diff (tests/visual/baselines/README.md)
foreach ($exe in 'src/Chronos.App/bin/Release/net10.0-windows/Chronos.exe',
'src/Chronos.Uploader/bin/Release/net10.0-windows/Chronos.Uploader.exe',
'src/Chronos.Setup/bin/Release/net10.0-windows/Chronos.Setup.exe') {
Start-Process -Wait $exe -ArgumentList '--capture', 'out/screenshots'
}
dotnet run --project src/Chronos.Tools -- screenshots diff out/screenshots --out out/screenshot-diff
The installer test is the last step of the windows job (Install, run, upgrade and remove in
.gitea/workflows/ci.yml): set $env:RUNNER_TEMP to an empty scratch folder and run that step's script. It installs,
upgrades and removes Chronos and the Uploader for the current user, so use a PC (or virtual machine) without an
installed copy of either.
Release process
- Make sure
mainis green, the Windows-only tests passed (on the Windows runner or a Windows PC) anddocs/CHANGELOG.md/docs/STATUS.mdare up to date. - Tag and push:
git tag v0.2.0 && git push origin v0.2.0(pre-releases:v0.2.0-rc.1; they are published as Gitea pre-releases, move:latestonly while no stable release exists and are ignored by the in-app update check). release.ymlthen, in its job Build, test and publish (SDK container):- validates the tag (SemVer 2.0 without build metadata: no leading zeros, no empty identifiers), builds with
ChronosVersionfrom the tag andChronosReleasesUrl(the repository the release goes to), runs the package guard, the i18n check and the Core, Data, Server and Tools tests; - cross-compiles the self-contained single-file win-x64 programs (Chronos, Uploader and Setup with ReadyToRun;
Server), checks them with
Chronos.Tools pe-check(GUI subsystem, icon, version, PerMonitorV2 manifest), signs them with osslsigncode when the signing secrets exist, packsChronos-Setup-<v>.exe(components Chronos, Uploader, Server) andChronos-Uploader-Setup-<v>.exe(Chronos.Tools pack-installer), signs the setups, zipsChronos-Server-win-x64-<v>.zipandChronos-win-x64-portable-<v>.zip(withportable.txt); - writes release notes from the Conventional Commits since the previous tag (
Chronos.Tools changelog); a stable tag starts from the previous stable tag, so its notes include what its release candidates brought; - computes
SHA256SUMSand publishes the Gitea release withChronos.Tools gitea-release: a draft first, every file uploaded and checked at its size, then published (as a pre-release for a tag with a-); - only with a separate releases repository (
RELEASES_REPO), and only when the tag is the newest stable release: copies into itdeploy/releases-repo/README.md,EULA.md,SECURITY.md,.gitea/ISSUE_TEMPLATE, the Unraid template and its icon (asunraid/), the compose file and.env.example(asdocker/),i18n/andSHA256SUMS, rewriting links to that repository and its image.
- validates the tag (SemVer 2.0 without build metadata: no leading zeros, no empty identifiers), builds with
- Its job Server image (the runner's own image with the docker CLI and the host's daemon) then builds the image for
linux/amd64 only (arm64 would need QEMU on the host) and pushes
gitea.encke-hake.ts.net/balbosoft/chronos-server:<v>, plus:latestwhen the tag is the highest stable version among the published releases, or the highest pre-release while none is stable (Chronos.Tools release-channels, by SemVer precedence; not Gitea'sreleases/latest, which is the most recently created one): an older tag published again, or a pre-release once a stable release exists, only gets its release and its:<v>image. WithoutREGISTRY_TOKENthis job fails with instructions while the release is already published: add the secret and re-run the job. - To publish an existing tag again (for example after adding a secret), run Release manually (Actions › Release ›
Run workflow) with the tag. The run builds
Chronos.Toolsfrom the tag: a tag older thanrelease-channels(v0.1.0-rc.1,v0.1.0-rc.2) gets its release and its:<v>image, with a warning, but moves neither the releases repository nor:latest.
Secrets and variables
Repository Settings › Actions › Secrets and Variables. With the defaults only the images need a secret.
| Name | Kind | Purpose |
|---|---|---|
REGISTRY_TOKEN |
secret | Access token (scope package: read and write) of a user who can write the owner's packages; release.yml and docker.yml push the server image with it. The workflow's own token (user gitea-actions) is refused by the organisation's registry. |
REGISTRY_USER |
variable (optional) | The user REGISTRY_TOKEN belongs to; default: the user who started the run (for a release, who pushed the tag). |
REGISTRY |
variable (optional) | Registry host; default: the host of PUBLIC_URL. |
PUBLIC_URL |
variable (optional) | Where people and programs reach Gitea; default https://gitea.encke-hake.ts.net. The runner itself uses the server address Gitea gives it. |
RELEASES_REPO |
variable (optional) | owner/name of another repository on the same Gitea that receives the releases; default: this repository. Give it a first commit (a README): Gitea refuses releases in an empty repository. Without RELEASES_TOKEN the release goes to this repository, with a warning. release.yml passes <PUBLIC_URL>/<that repository> to every build as the ChronosReleasesUrl MSBuild property, so the update check, licence and issue links of the binaries read the repository the release goes to (local builds default to https://gitea.encke-hake.ts.net/BalboSoft/Chronos). |
RELEASES_TOKEN |
secret (only with RELEASES_REPO) |
Access token with write access to that repository (scope repository: read and write): it creates the release there and pushes the copied content. |
WINDOWS_RUNNER |
variable (optional) | Label of a Windows act_runner in host mode; when set, CI runs its windows job there. |
SIGN_PFX_BASE64 |
secret (optional) | Base64 of the Authenticode code-signing certificate (.pfx). Without it builds are unsigned. |
SIGN_PASSWORD |
secret (optional) | Password of that .pfx. |
Everything else uses the workflow's own token: the checkouts, the source archive of the YAML check and the release in this repository.
Visibility
Today the BalboSoft organisation is not visible to anonymous visitors, so the update check, release downloads, the
raw compose and Unraid files and image pulls work only for people signed in to the Gitea
(docker login gitea.encke-hake.ts.net before pulling). They work for everyone once the owner makes the organisation
(and its packages) public, or publishes to a public RELEASES_REPO. Gitea has no private vulnerability reporting:
security problems go privately to the maintainers (SECURITY.md), never into a public issue.
First release (once)
- Create
REGISTRY_TOKEN: in the user Settings › Applications of a user who can write theBalboSoftpackages, generate an access token with scope package: read and write. Store it as the repository secretREGISTRY_TOKENand that user's name as the variableREGISTRY_USER(without it a run signs in as whoever triggered it). - Optional: make the
BalboSoftorganisation (and its packages) public, so other people get update notices, downloads and the image without an account. - Optional: register an act_runner in host mode on a Windows PC that has the .NET SDK of
global.json, Git for Windows and PowerShell 7 (act_runner register --no-interactive --instance https://gitea.encke-hake.ts.net --token <token from Settings › Actions › Runners> --labels windows:host, thenact_runner daemon), and set the repository variableWINDOWS_RUNNERto its label (windows). - Optional: a separate releases repository. Create it on the same Gitea with a README (so it has a default branch)
and issues enabled, set
RELEASES_REPOto itsowner/nameand store an access token with write access to it asRELEASES_TOKEN. - Optional: the signing secrets
SIGN_PFX_BASE64andSIGN_PASSWORD. - Once
mainholds the change, push the first pre-release tag:git tag v0.1.0-rc.1 && git push origin v0.1.0-rc.1. Follow it under Actions › Release; the files appear under Releases and the image under the organisation's Packages. - Have the EULA draft (
EULA.md) reviewed before the first stable release.
Server image, Compose and Unraid
- Image:
gitea.encke-hake.ts.net/balbosoft/chronos-server, tags:latest(newest stable release; before the first one, the newest pre-release),:<version>and:nightly(mainrebuilt every night, not for production); linux/amd64 only. - Compose:
deploy/docker/docker-compose.ymland.env.example, downloaded fromhttps://gitea.encke-hake.ts.net/BalboSoft/Chronos/raw/branch/main/deploy/docker/docker-compose.ymland…/deploy/docker/.env.example. - Unraid:
deploy/unraid/chronos.xml(repository…/chronos-server:latest, project and support links to this repository, template and icon from…/raw/branch/main/).release.ymlrewrites these addresses by their exact prefixes when it copies the files to a separate releases repository: keep them verbatim. To try the template, save it on the Unraid server as a user template (/boot/config/plugins/dockerMan/templates-user/my-chronos-server.xml) and pick chronos-server in Docker › Add container › Template. - Ports: in a container the server listens on 8080 and 8443 (read-only in the admin panel); the host ports clients use
are the Public HTTP/HTTPS port settings (
CHRONOS_PUBLIC_HTTP_PORT,CHRONOS_PUBLIC_HTTPS_PORT). Clients type the Client address of Settings › Network and TLS; LAN discovery reaches them only with host networking (Unraid network type Host), where the port mappings do nothing andCHRONOS_HTTP_PORT/CHRONOS_HTTPS_PORTmove the listening ports off ones another service uses. The user guide (deploy/releases-repo/README.md) explains both.
Repository layout
src/ Chronos.Core, Core.Windows, Data, Protocol, Server, Ui, App, Uploader, Setup, Tools
tests/ Chronos.Testing and one test program per area; fixtures/ (manifest of CC0 samples)
i18n/ <culture>/<Area>.resx string catalogs, GLOSSARY.md
deploy/ docker/ (Dockerfile, compose), unraid/ (template), releases-repo/ (README of a separate releases repository)
.gitea/ workflows/ (CI, release, nightly image, perf), scripts/ (YAML check, installer test), ISSUE_TEMPLATE/
branding/ SVG masters of the icons
docs/ BRIEF, ARCHITECTURE, DECISIONS, STATUS, CHANGELOG, ui/