# 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 (); users get the releases, the server image and the Unraid template from it too (see [Visibility](#visibility)). - User guide (install, update, Docker, Unraid, verifying downloads): [`deploy/releases-repo/README.md`](deploy/releases-repo/README.md) - Specification: [`docs/BRIEF.md`](docs/BRIEF.md) · working rules: [`CLAUDE.md`](CLAUDE.md) - Architecture and conventions: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) · decisions: [`docs/DECISIONS.md`](docs/DECISIONS.md) · status: [`docs/STATUS.md`](docs/STATUS.md) · changes: [`docs/CHANGELOG.md`](docs/CHANGELOG.md) - Visual design: [`docs/ui/DESIGN.md`](docs/ui/DESIGN.md) and `docs/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. ```sh 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: ```sh dotnet run --project src/Chronos.Server # admin panel https://localhost:8443/admin src/Chronos.App/bin/Release/net10.0-windows/Chronos.exe [--capture ] 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 `admin` with the temporary password in `out/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. ```powershell 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 1. Make sure `main` is green, the Windows-only tests passed (on the Windows runner or a Windows PC) and `docs/CHANGELOG.md` / `docs/STATUS.md` are up to date. 2. 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 `:latest` only while no stable release exists and are ignored by the in-app update check). 3. `release.yml` then, 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 `ChronosVersion` from the tag and `ChronosReleasesUrl` (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, packs `Chronos-Setup-.exe` (components Chronos, Uploader, Server) and `Chronos-Uploader-Setup-.exe` (`Chronos.Tools pack-installer`), signs the setups, zips `Chronos-Server-win-x64-.zip` and `Chronos-win-x64-portable-.zip` (with `portable.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 `SHA256SUMS` and publishes the Gitea release with `Chronos.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 it `deploy/releases-repo/README.md`, `EULA.md`, `SECURITY.md`, `.gitea/ISSUE_TEMPLATE`, the Unraid template and its icon (as `unraid/`), the compose file and `.env.example` (as `docker/`), `i18n/` and `SHA256SUMS`, rewriting links to that repository and its image. 4. 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:`, plus `:latest` when 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's `releases/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 `:` image. Without `REGISTRY_TOKEN` this job fails with instructions while the release is already published: add the secret and re-run the job. 5. 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.Tools` from the tag: a tag older than `release-channels` (`v0.1.0-rc.1`, `v0.1.0-rc.2`) gets its release and its `:` 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 `/` 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) 1. Create `REGISTRY_TOKEN`: in the user *Settings › Applications* of a user who can write the `BalboSoft` packages, generate an access token with scope *package: read and write*. Store it as the repository secret `REGISTRY_TOKEN` and that user's name as the variable `REGISTRY_USER` (without it a run signs in as whoever triggered it). 2. Optional: make the `BalboSoft` organisation (and its packages) public, so other people get update notices, downloads and the image without an account. 3. 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 --labels windows:host`, then `act_runner daemon`), and set the repository variable `WINDOWS_RUNNER` to its label (`windows`). 4. 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_REPO` to its `owner/name` and store an access token with write access to it as `RELEASES_TOKEN`. 5. Optional: the signing secrets `SIGN_PFX_BASE64` and `SIGN_PASSWORD`. 6. Once `main` holds 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*. 7. 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), `:` and `:nightly` (`main` rebuilt every night, not for production); linux/amd64 only. - Compose: `deploy/docker/docker-compose.yml` and `.env.example`, downloaded from `https://gitea.encke-hake.ts.net/BalboSoft/Chronos/raw/branch/main/deploy/docker/docker-compose.yml` and `…/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.yml` rewrites 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 and `CHRONOS_HTTP_PORT` / `CHRONOS_HTTPS_PORT` move 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/ /.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/ ```