ARCHITECTURE gains the module map, hosts, job kinds with their handlers, the data flow and the extension points; STATUS records the measured performance gates and the Phase 8 next steps; CHANGELOG summarises everything built under Unreleased; README covers build, tests, CI, the release process, the secrets and how to bootstrap the public releases repository. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
Titano (development repository)
Time-lapse ecosystem: Titano (Windows desktop client), Titano Server (Linux/Docker and Windows) and Titano Uploader (Windows), sharing one C#/.NET 10 engine with zero third-party packages. This repository is private; users get releases, the Docker image and the Unraid template from the public releases repository.
- 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 Titano.slnx -c Release
# Tests (one program per area; --filter text|category:name, --junit file, --verbose)
dotnet run --project tests/Titano.Core.Tests -c Release -- --junit out/core.xml
dotnet run --project tests/Titano.Data.Tests -c Release
dotnet run --project tests/Titano.Server.Tests -c Release
dotnet run --project tests/Titano.Core.Windows.Tests -c Release # Windows
dotnet run --project tests/Titano.App.Tests -c Release # Windows
# PostgreSQL integration tests (16 or 17)
TITANO_TEST_PG="Host=127.0.0.1;Port=5432;Database=titano_test;Username=titano;Password=…;SslMode=disable" \
dotnet run --project tests/Titano.Data.Tests -c Release
# Performance gates (500,000-photo library, 100,000-frame rebuild; minutes)
TITANO_PERF=1 dotnet run --project tests/Titano.Data.Tests -c Release -- --filter category:perf --verbose
# Checks run by CI
dotnet run --project src/Titano.Tools -- package-guard
dotnet run --project src/Titano.Tools -- i18n check
dotnet run --project src/Titano.Tools -- xaml-lint
dotnet format whitespace Titano.slnx --verify-no-changes
# CC0 RAW samples for the decoder tests (tests/fixtures/manifest.json explains how to fill in URLs)
dotnet run --project src/Titano.Tools -- fixtures
Run:
dotnet run --project src/Titano.Server # admin panel https://localhost:8443/admin
src/Titano.App/bin/Release/net10.0-windows/Titano.exe [--capture <folder>]
src/Titano.Uploader/bin/Release/net10.0-windows/Titano.Uploader.exe
docker compose -f deploy/docker/docker-compose.yml up -d
The server reads /data/server.json (TITANO_DATA_PATH) and TITANO_* environment variables;
Titano.Server --help lists them. On Linux it needs PostgreSQL; on Windows it defaults to SQLite.
CI
| Workflow | When | What |
|---|---|---|
.github/workflows/ci.yml |
push to main, pull requests |
Windows + Linux build (warnings are errors), all tests, package guard, i18n check, XAML lint, format check, CC0 fixtures (a warning per missing sample), screenshots (--capture, also pushed to the ci-screenshots branch for same-repository PRs), Windows program artifacts, PostgreSQL 16/17 integration, Docker image smoke test |
.github/workflows/docker.yml |
nightly | ghcr.io/<owner>/titano-server:nightly (multi-arch) |
.github/workflows/perf.yml |
weekly, manual | Performance gates on SQLite and PostgreSQL 17; timings in the job summary |
.github/workflows/release.yml |
tag v*, manual re-publish |
The release (below) |
Release process
- Make sure
mainis green 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 GitHub pre-releases, get no:latestimage and are ignored by the in-app update check). release.ymlthen:- validates the tag, builds with
TitanoVersionfrom the tag and runs every test on Windows; - publishes self-contained single-file programs, signs them when signing secrets exist, packs
Titano-Setup-<v>.exeandTitano-Uploader-Setup-<v>.exe(Titano.Tools pack-installer), signs the setups, zipsTitano-Server-win-x64-<v>.zipandTitano-win-x64-portable-<v>.zip; - writes release notes from the Conventional Commits since the previous tag (
Titano.Tools changelog); - builds and pushes
ghcr.io/<owner>/titano-server:<v>(and:latestfor stable tags) for amd64 and arm64; - computes
SHA256SUMS, updates the public releases repository and creates (or updates) the GitHub release there.
- validates the tag, builds with
- To publish an existing tag again (for example after adding a secret), run Release manually with the tag.
Secrets and variables
| Name | Kind | Purpose |
|---|---|---|
RELEASES_TOKEN |
secret | Fine-grained PAT with Contents: read and write on the public releases repository. Without it the release is created in this (private) repository, which clients cannot see. |
RELEASES_REPO |
variable (optional) | owner/name of the public repository; default <owner>/titano-releases. Builds embed it through the TitanoReleasesRepo MSBuild property (default alby96/titano-releases), so keep the two in line. |
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. |
GITHUB_TOKEN pushes the image to GHCR; no other secret is used.
Bootstrapping the public releases repository
- Create a public repository named
titano-releasesunder the same owner (or setRELEASES_REPO), with a README so it has a default branch. Enable Issues and Private vulnerability reporting (Settings › Security). - Create the fine-grained PAT (repository access: only that repository; permissions: Contents read/write) and store
it as the
RELEASES_TOKENsecret of this repository. - Push a pre-release tag (
v0.1.0-rc.1). The release job copiesdeploy/releases-repo/(README, EULA draft, SECURITY policy, issue forms), the Unraid template and its icon, the compose file and.env.example, the dark screenshots,i18n/and the latestSHA256SUMSinto the public repository, rewriting links to its name, then creates the release with the installers. - After the first image push, open the
titano-serverpackage on GHCR › Package settings and set its visibility to Public (GitHub offers no API for this; the release summary reminds you). - Have the EULA draft (
deploy/releases-repo/EULA.md) reviewed before the first stable release. - In Unraid, add
https://github.com/<owner>/titano-releasesunder Docker › Template repositories to validate the template.
Repository layout
src/ Titano.Core, Core.Windows, Data, Protocol, Server, Ui, App, Uploader, Setup, Tools
tests/ Titano.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/ (public repository content)
branding/ SVG masters of the icons
docs/ BRIEF, ARCHITECTURE, DECISIONS, STATUS, CHANGELOG, ui/