diff --git a/README.md b/README.md index 15ad8743..c00d571e 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ Time-lapse ecosystem: **Chronos** (Windows desktop client), **Chronos Server** ( 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) +- Deploy guide (every variable, ports, TLS, upgrades, backup, troubleshooting): [`docs/deploy/`](docs/deploy/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: diff --git a/docs/BRIEF.md b/docs/BRIEF.md index 1e164df3..3cac14b1 100644 --- a/docs/BRIEF.md +++ b/docs/BRIEF.md @@ -508,6 +508,16 @@ The archive is the source of truth; the database is an index that can be rebuilt │ └── *.pending.json journals of an ingest, a photo deletion, a frame replacement (replace.pending.json, a conversion or its undo; amended 2026-10-26, R7) or a restore a crash interrupted (below) ``` +The root-level folders above (`.chronos/` with `locks/`, `journal/`, `staging/`, `trash/`, +`trash/photos/` and `trash/videos/`) exist from the start (amended 2026-11-06, owner review 4 +R3): whatever path is chosen as the archive root, on the desktop or the server (Docker or +Windows), gets them when the archive is created, adopted or opened, and only the missing +ones are made; nothing existing is touched. The root itself is created only for a new +archive. A create whose folders cannot be made fails with the reason (drive or share +unavailable, permission denied, read-only, a file in the way); an open never fails for it: +the problem is logged and shown (§14.8 dashboard, `/health`). Per-sequence folders and the +trash's `.erasing`/`.erased` are still made when needed. + `sequence.json` (canonical, versioned, written atomically): `{ id, title, camera, lens, frames: [{ i, file, size, sha256, capturedAt, exposure, fNumber, iso, focal, bias, wb, orientation, w, h, format, previewOffset, previewLength, flags, source? }], @@ -1916,11 +1926,16 @@ server*). The files stay in each sequence's `exports/` (§7); the section never except into the trash. - Toolbar: search (title, preset, file name), Kind (All, Videos, Stills, Sequences), Codec and Year (the values present), Source (All, This PC, Server, Not sent), Order (Newest, - Oldest, Largest, Title), cards or list (kept), *Refresh*, *Clear filters* and the + Oldest, Largest, Title), cards, list or board (kept; board amended 2026-11-06, owner + review 4 R1), *Refresh*, *Clear filters* and the selection count. The Export footer's *Videos (n)* and the Render menu's *Videos* open it on one sequence, shown as a chip whose × clears that filter only. -- A card: the poster (the sequence's cover, or the still itself), title, preset, size · - codec · duration · bytes, date, and chips *Here*, *On server*, *Copied*, *Missing*, *Not +- The board (owner review 4 R1): the work done in two lanes, *Published* (this PC's and + the server's renders) and *Workspace* (the workspace's renders, sent or not), newest + first, each with its count, under the same filters, selection and actions; a sent + workspace render is in both lanes, its workspace card marked *Sent*. +- A card: the poster (the sequence's cover, or the still itself), title, a line starting + with the preset (preset · codec · duration · bytes, amended 2026-11-06), date, and chips *Here*, *On server*, *Copied*, *Missing*, *Not sent*. The list has the same columns, Preset, Format and Date hidden while the player is open (the row's tooltip keeps them). - Actions on the selection (toolbar) or a row (its menu, on the selection when the row is @@ -2775,7 +2790,10 @@ operations; it queues no deep analysis (the API's `bulk/jobs` takes `deep`). Videos (amended 2026-11-05, owner review 1 R3/R8/R9; §12.10, §14.3), the page after Library in the sidebar. It manages the server's renders and never edits: nothing on it renders or changes a project (owner review 2, R6). -- `#/videos` lists every render of the server as cards or a list (kept in the browser): +- `#/videos` lists every render of the server as cards, a list or a board (kept in the + browser; the board amended 2026-11-06, owner review 4 R1: lanes *Published* and + *Workspace*, the latter holding project renders produced by another machine than the + server, per `producedBy`): search, Kind, Codec, Year and Order, the filters in the address; `#/videos?sequence=` shows one sequence's, named by a chip whose × clears that filter only (the sequence named from its own record when none of its videos is on the page); *Load more* by cursor. @@ -2907,7 +2925,9 @@ ports clients use when a container's ports are published as others: LAN discover redirect and the admin panel's client address use them; also the admin panel's *Public HTTP/HTTPS port*, `PublicHttpPort`/`PublicHttpsPort` in `server.json`, applied at once; amended 2026-11-04, owner review 3), `CHRONOS_TLS_MODE=auto|pem|proxy`, -`CHRONOS_TLS_CERT`, `CHRONOS_TLS_KEY`, `CHRONOS_SERVER_NAME`, `CHRONOS_LANG=en`, +`CHRONOS_TLS_CERT`, `CHRONOS_TLS_KEY`, `CHRONOS_TRUSTED_PROXIES=127.0.0.0/8, ::1/128` (TLS +mode proxy: the addresses or CIDR networks whose `X-Forwarded-*` headers count; listed here +on 2026-11-06, owner review 1 phase 6, as the server already read it), `CHRONOS_SERVER_NAME`, `CHRONOS_LANG=en`, `CHRONOS_PARALLELISM` (photos the running job processes at once; `CHRONOS_WORKERS`, its former name, still sets it), `CHRONOS_PRIORITY_QUEUE=false`, `CHRONOS_DISCOVERY=true` (LAN UDP beacon; it leaves a container only with host networking, Unraid network type Host: amended 2026-11-04, owner @@ -2938,6 +2958,13 @@ at `/videos` with `CHRONOS_VIDEOS_PATH=/videos`; remove both to turn copying off Windows: `Chronos.Server.exe` runs as console or Windows Service (`sc create`), SQLite or PostgreSQL. +The deploy guide `docs/deploy/` (README, `docker.md`, `unraid.md`, `desktop.md`) documents +every variable above with its default, the volumes, the ports and public ports, the TLS +modes and the fingerprint, upgrades (`:latest`, `:`, `:nightly`; migrations at +start, forward only), backup and restore, PostgreSQL and troubleshooting; the compose file, +the Unraid template and `deploy/releases-repo/README.md` say the same, and a change to one +updates the others (amended 2026-11-06, owner review 1 phase 6). + --- ## 15. Chronos Uploader @@ -3195,7 +3222,9 @@ Icon `https://gitea.encke-hake.ts.net/BalboSoft/Chronos/raw/branch/main/branding `release.yml` rewrites these exact prefixes for a separate releases repository (§19.4), so they stay verbatim. (Amended 2026-10-23, R2.) Document (in the README) how to install the template as a user template (Unraid's template repositories read GitHub and GitLab -addresses, not Gitea's) and to pair it with the official PostgreSQL template. +addresses, not Gitea's) and to pair it with the official PostgreSQL template; `docs/deploy/unraid.md` +gives the whole procedure, the fields, host ports other than 8080/8443 with their public +ports, the array view, upgrades and backup (amended 2026-11-06, owner review 1 phase 6). --- @@ -3393,7 +3422,10 @@ questions asked and the answers; DECISIONS rows give the reasons. | 2026-11-04 | Owner review 3 (ports) | §12.7, §14.8, §14.9, §15, §19.6 | The public HTTP/HTTPS ports are server settings as well as variables (a variable locks them), applied at once; in a container the listening ports are locked to the template's; the admin panel's Network and TLS shows the container's ports, the public ports and the client address with Copy; clients read an address without scheme or port as port 8443 and report an address that answers as something else, never offering its certificate for trust; the Unraid template and compose gain *Public HTTP port*. | | 2026-11-04 | Owner review 1, R5/R6 (phase 4: visual crop, transforms, looks) | §10.3, §11.2, §11.4, §12.3, §14.3, §14.7 | The crop is edited on the preview with handles, always locked to the output aspect, in the view frame (turned, straightened); the chosen proportions win: a fixed-size preset is a box the aspect is fitted in (4K at 9:16 = 2160×3840), "source" keeps the preset, the preset name stays and *Output size* shows the result; the Camera step gains Rotation (quarter turns), Mirror, Flip, Straighten (±15°, automatic cover zoom), Crop size/X/Y and Reset framing, the crop-margin and offset rows go; a turn or mirror keeps the content (crop, keyframes, a transposed aspect); the Exposure step ends with a Look (eight built-in colour looks with a strength), applied after stacking and before the knee; one Core path for render, server, nodes and preview; settings format 2 written only when a transform or look is used, read-only in older builds; `server/info` and node registrations announce the settings format, and nothing an older server or node would get wrong is sent to it; the advisor works on the view as shown. | | 2026-11-05 | Owner review 1, R3/R8/R9 (phase 5: export panel and Render menu, export options, videos library) | §5, §7, §11.1, §11.3, §11.4, §11.5, §12.1, §12.3, §12.5, §12.8, §12.10, §14.3, §14.6, §14.7, §14.8, §14.9, §19.6 | The header's *Render ▾* reads "Render" at a fixed width, its tooltip giving the details, its menu the recommended, batch and recent presets, *Other presets ›* by group with a details line, *Render batch*, *Add to queue*, *Save frame ›* and *Videos*; the Export step's cards become a grouped preset table and its Output panel four collapsible groups (Output, Encoding, Playback, File) with summaries, open state kept by the app, and a fixed footer; advanced encoding (rate control, bit rate or quality, keyframes in seconds, B-frames, profile) and standard resolutions over the existing overrides, no format raise; playback (reverse, boomerang, loops, fades to black, hold at the end) as an output program, settings format 3 written only when used, read-only in older builds and never sent to an older server or node; *Save frame* saves one corrected frame as PNG, JPEG or TIFF 16-bit (kind `still`, format-3 jobs); renders record their SHA-256 and kind, copies are recorded (migration 0010); one Videos library on the desktop (a rail section on Ctrl+4, Archive, Jobs and Server moving to Ctrl+5…7; this PC's, the server's and unsent workspace renders merged; an in-process player) and on the admin panel (a Videos page with a browser player); a hash-verified `video-copy` job (stored as 24) into a flat videos folder (Settings › Archive, the server's `videosPath`, `CHRONOS_VIDEOS_PATH`, the optional `/videos` volume); delete into `trash/videos/` behind a dry run and fingerprint, restore with the same id after a hash check; `/api/v1/videos`, the `videos` capability, `RenderDto` `sha256` and `kind`. | +| 2026-11-06 | Owner review 1, phase 6 (deploy guide) | §14.9, §19.6 | The deploy guide `docs/deploy/` (Docker, Unraid, desktop) documents every `CHRONOS_*` variable with its default, the volumes, ports and public ports (host 8087/8444 → container 8080/8443 with Public HTTPS port 8444), TLS modes and the fingerprint, upgrades and migrations, backup and restore, PostgreSQL and troubleshooting, kept in step with the compose file, the Unraid template and the release's user guide; `CHRONOS_TRUSTED_PROXIES`, which the server already read, is listed in §14.9. | +| 2026-11-06 | Owner review 4, R1 (work board) | §12.10, §14.8 | Every video made or published in one board, the published ones apart from the work in a workspace: a third Videos layout *Board* (kept as the cards/list choice is) on the desktop and on the admin panel's Videos page, two lanes *Published* and *Workspace*, newest first, each with its count and the list's filters; a sent workspace render is in both lanes, its ledger row marked *Sent*; cards start with the preset; sizes keep number and unit together (issue #29). | | 2026-11-06 | Owner review 4, R2 | §21 | Chronos sends nothing about its use: the usage counts consent is gone from the first run and from Settings › General (and its setting, an old settings file still loading), monetization counts no impressions; the diagnostics bundle is only saved locally. | +| 2026-11-06 | Owner review 4, R3 (archive structure) | §7, §12.8, §14.8, §14.9 | The archive's root-level folder tree (`.chronos` with `locks`, `journal`, `staging`, `trash`, `trash/photos`, `trash/videos`) is created inside the chosen archive path when an archive is created, adopted or opened, on the desktop and on the server, in Docker and on Windows; existing folders and files are never touched; a create whose tree cannot be made fails with the reason, an open logs and shows it (the dashboard's *Archive incomplete*, `/health` archive "incomplete"); Settings › Archive folder creates the archive in a folder that has none (issue #31). | ## Appendix A — `CLAUDE.md` content (create verbatim in Phase 0, keep updated) diff --git a/docs/STATUS.md b/docs/STATUS.md index a2fe018f..e1521696 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -14,10 +14,11 @@ by its `windows` job once a Windows runner is registered (`WINDOWS_RUNNER`), and | 6 Engine, encoding, editor | Done: render pipeline, MP4/AVI/GIF/APNG/image sequences, Media Foundation H.264/HEVC/AV1 with managed fallbacks; the sequence editor (Frames, Exposure, Camera, Motion and Export tabs, preview tools, section charts, curve editor, undo/redo, batch export) for local and server sequences. Gate: self-test suite green; the in-house inspector validates the containers the tests write; the encoder in use is logged. Playback: MediaPlayer opens the Media Foundation output and a source reader decodes its first frame (Windows tests). The pixel diff of every `--capture` screen against `tests/visual/baselines` (`screenshots diff`, BRIEF §20.2) is wired into CI but not armed: no baseline is committed yet, so the step compares nothing and only warns until the first baselines are accepted from `ci-screenshots` (Next steps). | | 7 Server, sync, uploader | Done: server (API, auth, uploads, jobs, render nodes, events, admin panel with light and dark themes, Windows service), Uploader, client sync (sync table, conflicts with *Save both*, proxies kept offline, metered pause), server sequences edited with proxies and rendered where the originals are, this PC as a render node. Gate covered in-process: a sequence uploaded from one PC downloads identically on another, interrupted uploads and downloads resume, server events update a PC, renders run on a node and on the server's managed fallback, jobs resume after a restart, sign-ins and administrative actions are audited. The run with two real PCs and the Uploader against the Docker server is part of the release test. | | 8 Release readiness | Release pipeline end to end (installers, portable and server zips, SHA256SUMS, release notes, optional signing, server image in the Gitea container registry, optional separate releases repository), update check with verified download, scrubbed diagnostics bundles (desktop and server), performance gates, 38 cultures (`en`, `it` and 36 machine translations with glossaries and independent reviews), RTL pass (`ar`, `he`: mirrored windows, left-to-right islands for media, charts, numbers and paths; any right-to-left culture added later follows), accessibility pass (names, live regions, keyboard paths for charts and the curve editor). The installer test (silent install of the packed installers, run, upgrade in place, uninstall: files, Add/Remove Programs, shortcuts, file type, user data kept, exit codes) runs in CI's `windows` job on a Windows runner. Pending: the interactive install on a real PC, Unraid template validation on a real server. | -| 8.1 Owner review 1 | In progress (request, answers and plan: `docs/requests/2026-10-15-owner-review-1.md`). Phase 1 done: stalled thumbnail and proxy jobs no longer fail and stay Running (frame-counted progress, bounded time left, final state always written); the editor's cancelled decodes stay in their tasks (no debugger stops in `WicDecoderProvider.cs`); WIC decodes RAW only through the Raw Image Extension and never DNG; GoPro DNGs converted by Adobe software are DNGs, developed natively for videos, read through their embedded preview for analyses and previews, and reclassified in existing archives by the next light analysis. Phase 2 done: jobs run one at a time on the desktop and the server; Parallelism is how many photos the running job processes at once (thumbnail and proxy passes, tier probes, deep analysis, render decodes); pausing the running job starts the next; an optional priority queue by job kind (Settings › Rendering, admin panel › Settings › Jobs, `CHRONOS_PRIORITY_QUEUE`) pauses lower jobs and resumes them by themselves; `CHRONOS_PARALLELISM` replaces `CHRONOS_WORKERS`. Phase 3a done: the rail is 200 px and collapses to icons with ≡ or Ctrl+B (tooltips then name the sections, the choice saved at once); the admin panel's sidebar is 256 px and collapses the same way. Phase 3b done: the Sequence section is now Edit, one sequence at a time chosen in a picker inside the section (Change sequence, Ctrl+O; the sequence edited last selected first), and the editor's tabs are the steps of a guided, freely navigable path from a new Analysis step (every finding with the step that deals with it) to Export, each step showing where it stands, with Previous and Next. Phase 4 done and released as `v0.1.0-rc.12` (issue #19, `188b2c2e`; one adversarial review round, 30 findings, all confirmed and fixed, and a final check that fixed one more; strings in all 38 languages; 31 screenshot baselines accepted): the crop edited on the preview with eight handles, always locked to the output's aspect, in the view frame, by mouse, keyboard (Enter selects) and Crop size/X/Y (R5); the chosen proportions win: a fixed-size preset is a box the aspect is fitted in (`RenderSize`: 4K at 9:16 = 2160×3840), "source" keeps the preset, *Output size* on the Export step; Rotation (quarter turns), Mirror, Flip and Straighten (±15°, automatic cover zoom, the grid while it moves) in the Camera step inside the one warp (`FrameOrientation`), a turn or mirror keeping the content (`OrientationEdit`: crop, keyframes, transposed aspect), Reset framing; eight built-in colour looks with a strength at the end of the Exposure step, after stacking and before the knee (`LookFilter`, `FrameFinish`), the same in the render, on the server, render nodes and the preview; settings format 2 written only while a transform or look is used (`ProjectSettings.RequiredFormat`), read-only in older builds; `server/info` and node registrations announce the settings format, jobs carry the one they need (`RenderRules.RequiredFormat`), and nothing an older server or node would get wrong is sent to it (Sync, Send and render, the Library's Render, a remote editor's save); encoder limits read either way round; the advisor on the view as shown. Also fixed on the way (issue #20): project text is LF on every OS, stored CRLF versions compare equal. Known limitations: an older desktop renders a chosen aspect at the preset's ratio on its own; the server's settings format is cached for a minute; the new Camera rows and the Straighten slider binding have no on-screen test. Phase 5 done, to be released as `v0.1.0-rc.13` (issue #21; eight parcels and an integration, one adversarial review round whose findings are all fixed; strings in English and Italian, the other 36 languages being imported): the header's *Render ▾* at a fixed width with its details in the tooltip and a structured menu (recommended, batch and recent presets, *Other presets ›* by group with a details line, *Render batch*, *Add to queue*, *Save frame ›*, *Videos*; `RenderMenu`, hierarchical two-line `SplitButton` entries) (R3); the Export step's grouped preset table, four collapsible groups with summaries kept per user (`ExportGroups`, `AppSettings.EditorGroups`) and a fixed footer (R3); advanced encoding (rate control, bit rate or quality, keyframes in seconds, B-frames, profile, gated per codec and depth) and standard resolutions over the existing overrides, no format raise (R8); playback (reverse, boomerang, loops, fades to black, hold) as the Core `OutputProgram` between the plan and the encoder, with estimates, progress and star trails following it, settings format 3 written only when used (R8); *Save frame* as a still render (PNG, JPEG, TIFF 16-bit; `RenderTarget.StillFrame`, `StillImageSession`; format-3 jobs, also from workspace projects) (R8); render SHA-256 and kind, render copies (migration 0010); the videos library (`VideoLibrary`, `VideoTrash` into `trash/videos/` with a dry run, fingerprint and journal, restore with the same id after a hash check; `VideoCopyJobHandler`, `video-copy` stored as 24, into a flat, hash-verified videos folder) on the desktop as the Videos section (Ctrl+4, Archive/Jobs/Server Ctrl+5…7; this PC's, the server's and unsent workspace renders merged, an in-process player) and on the server as `/api/v1/videos`, the `videos` capability, the admin panel's Videos page and the trash's Videos entries, `CHRONOS_VIDEOS_PATH` and the optional `/videos` volume (R9). Known limitations: GIF and APNG show their first frame in the desktop player; HEVC plays where Windows has its extension; older renders are hashed on first copy, delete or restore; the new screens have no screenshot scenes or baselines yet. Next: phase 6 (issue #22), then `v1.0.0` (issue #23). | +| 8.1 Owner review 1 | In progress (request, answers and plan: `docs/requests/2026-10-15-owner-review-1.md`). Phase 1 done: stalled thumbnail and proxy jobs no longer fail and stay Running (frame-counted progress, bounded time left, final state always written); the editor's cancelled decodes stay in their tasks (no debugger stops in `WicDecoderProvider.cs`); WIC decodes RAW only through the Raw Image Extension and never DNG; GoPro DNGs converted by Adobe software are DNGs, developed natively for videos, read through their embedded preview for analyses and previews, and reclassified in existing archives by the next light analysis. Phase 2 done: jobs run one at a time on the desktop and the server; Parallelism is how many photos the running job processes at once (thumbnail and proxy passes, tier probes, deep analysis, render decodes); pausing the running job starts the next; an optional priority queue by job kind (Settings › Rendering, admin panel › Settings › Jobs, `CHRONOS_PRIORITY_QUEUE`) pauses lower jobs and resumes them by themselves; `CHRONOS_PARALLELISM` replaces `CHRONOS_WORKERS`. Phase 3a done: the rail is 200 px and collapses to icons with ≡ or Ctrl+B (tooltips then name the sections, the choice saved at once); the admin panel's sidebar is 256 px and collapses the same way. Phase 3b done: the Sequence section is now Edit, one sequence at a time chosen in a picker inside the section (Change sequence, Ctrl+O; the sequence edited last selected first), and the editor's tabs are the steps of a guided, freely navigable path from a new Analysis step (every finding with the step that deals with it) to Export, each step showing where it stands, with Previous and Next. Phase 4 done and released as `v0.1.0-rc.12` (issue #19, `188b2c2e`; one adversarial review round, 30 findings, all confirmed and fixed, and a final check that fixed one more; strings in all 38 languages; 31 screenshot baselines accepted): the crop edited on the preview with eight handles, always locked to the output's aspect, in the view frame, by mouse, keyboard (Enter selects) and Crop size/X/Y (R5); the chosen proportions win: a fixed-size preset is a box the aspect is fitted in (`RenderSize`: 4K at 9:16 = 2160×3840), "source" keeps the preset, *Output size* on the Export step; Rotation (quarter turns), Mirror, Flip and Straighten (±15°, automatic cover zoom, the grid while it moves) in the Camera step inside the one warp (`FrameOrientation`), a turn or mirror keeping the content (`OrientationEdit`: crop, keyframes, transposed aspect), Reset framing; eight built-in colour looks with a strength at the end of the Exposure step, after stacking and before the knee (`LookFilter`, `FrameFinish`), the same in the render, on the server, render nodes and the preview; settings format 2 written only while a transform or look is used (`ProjectSettings.RequiredFormat`), read-only in older builds; `server/info` and node registrations announce the settings format, jobs carry the one they need (`RenderRules.RequiredFormat`), and nothing an older server or node would get wrong is sent to it (Sync, Send and render, the Library's Render, a remote editor's save); encoder limits read either way round; the advisor on the view as shown. Also fixed on the way (issue #20): project text is LF on every OS, stored CRLF versions compare equal. Known limitations: an older desktop renders a chosen aspect at the preset's ratio on its own; the server's settings format is cached for a minute; the new Camera rows and the Straighten slider binding have no on-screen test. Phase 5 done, to be released as `v0.1.0-rc.13` (issue #21; eight parcels and an integration, one adversarial review round whose findings are all fixed; strings in English and Italian, the other 36 languages being imported): the header's *Render ▾* at a fixed width with its details in the tooltip and a structured menu (recommended, batch and recent presets, *Other presets ›* by group with a details line, *Render batch*, *Add to queue*, *Save frame ›*, *Videos*; `RenderMenu`, hierarchical two-line `SplitButton` entries) (R3); the Export step's grouped preset table, four collapsible groups with summaries kept per user (`ExportGroups`, `AppSettings.EditorGroups`) and a fixed footer (R3); advanced encoding (rate control, bit rate or quality, keyframes in seconds, B-frames, profile, gated per codec and depth) and standard resolutions over the existing overrides, no format raise (R8); playback (reverse, boomerang, loops, fades to black, hold) as the Core `OutputProgram` between the plan and the encoder, with estimates, progress and star trails following it, settings format 3 written only when used (R8); *Save frame* as a still render (PNG, JPEG, TIFF 16-bit; `RenderTarget.StillFrame`, `StillImageSession`; format-3 jobs, also from workspace projects) (R8); render SHA-256 and kind, render copies (migration 0010); the videos library (`VideoLibrary`, `VideoTrash` into `trash/videos/` with a dry run, fingerprint and journal, restore with the same id after a hash check; `VideoCopyJobHandler`, `video-copy` stored as 24, into a flat, hash-verified videos folder) on the desktop as the Videos section (Ctrl+4, Archive/Jobs/Server Ctrl+5…7; this PC's, the server's and unsent workspace renders merged, an in-process player) and on the server as `/api/v1/videos`, the `videos` capability, the admin panel's Videos page and the trash's Videos entries, `CHRONOS_VIDEOS_PATH` and the optional `/videos` volume (R9). Known limitations: GIF and APNG show their first frame in the desktop player; HEVC plays where Windows has its extension; older renders are hashed on first copy, delete or restore; the new screens have no screenshot scenes or baselines yet. Phase 6 in progress (issue #22), with owner review 4, for `v0.1.0-rc.14`: the deploy guide `docs/deploy/` (README, `docker.md` with every `CHRONOS_*` variable and its default, volumes, ports and public ports, TLS and the fingerprint, upgrades, backup and restore, PostgreSQL, troubleshooting; `unraid.md` with the owner's host ports 8087/8444 and Public HTTPS port 8444; `desktop.md` with Setup, portable mode and updates), BRIEF §14.9 (`CHRONOS_TRUSTED_PROXIES` listed), §19.6 and §24 (every amendment since owner review 1 listed); full verification before the release. Then `v1.0.0` (issue #23). | | 8.2 Chronos on Gitea | Done (request: `docs/requests/2026-10-23-chronos-gitea.md`): Titano renamed Chronos everywhere, translations' grammar included; repository, update check, links, issue forms and registry moved to the self-hosted Gitea; Gitea Actions CI, release, nightly image and performance workflows for the Linux runner, with the Windows programs cross-compiled and checked (`pe-check`); new `Chronos.Tools` commands `zip`, `gitea-release`, `postgres-ci`, `pe-check`. Pre-releases `v0.1.0-rc.1` and `v0.1.0-rc.2` (the update check builds its links from `ChronosReleasesUrl`, since Gitea's use its LAN ROOT_URL) published; `REGISTRY_TOKEN` is set and the `v0.1.0-rc.2` server image is in the registry. | | 8.3 Owner review 2 | Done (request, answers and plan: `docs/requests/2026-10-26-owner-review-2.md`). Phase 1 done and released as `v0.1.0-rc.3` (one adversarial review round, 19 findings fixed; strings in all 38 languages): `:latest` follows the highest stable release, or the highest pre-release while none is stable (`Chronos.Tools release-channels`), `:nightly` stays the nightly build of `main` (R1); `CHRONOS_SPACE_PATH` and the Unraid template's *Array view* (`/mnt/user0/` read-only at `/space`) make the admin panel show the array's free space, the cache apart as *Write volume*, the file system in the tooltip, and completing an upload checks the archive volume first (507, resumable) (R2); the Settings icon is a toothed gear and the admin panel docks Settings at the foot of its sidebar (R4); About is the last page of Settings on the desktop and the last group of Settings on the admin panel (R5); Import › Folder… › *Whole folder* imports a folder as one sequence per format, titled after the folder (R9). Phase 2 done and released as `v0.1.0-rc.4` (one adversarial review round, 35 findings fixed; strings in all 38 languages): scheduled jobs (R10) — schedules (migration 0007) with an in-house recurrence form, one scheduler per host claiming runs by compare-and-set with catch-up, and Jobs › Scheduled on the desktop and the admin panel (`/api/v1/schedules`, `scheduleChanged`); every timer that queued work is a visible system schedule (server: archive scan, upload clean-up every 6 h, index backup at 03:00, job history and audit log clean-ups; desktop: archive scan, daily index backup, housekeeping with cache trim), the archive still scanned at start; new Backup and Clean-up jobs, duplicates and orphans reports as jobs, one backup retention, the trash only reported; log settings (R11) — file and console levels, retention, file and total size limits, daily or hourly rotation, audit retention (the audit clean-up schedule's) and the diagnostics share in the admin panel's Settings › Logs (`CHRONOS_LOG_*`, `lockedBy`) and the desktop's Settings › Advanced; the server's files take Debug and Trace again, and logging never fails a job. Phase 3 done and released as `v0.1.0-rc.5` (one adversarial review round and two fix rounds, 40 findings fixed; strings in all 38 languages; Library, photo delete and restore and the web upload tried by hand): the admin panel manages and never edits (R6) — a Library page (facets filters, cards or list, keyboard selection, mass Analyse, Proxies, Thumbnails, Verify, Tags, Export CSV and Delete, 1,000 sequences a request), a sequence's page (inline title, tags, rating, notes, photo viewer, cover, downloads, photo delete) and the trash view (Restore, Empty… behind a dry run, the typed word and a fingerprint); photos deleted into `trash/photos` under crash-safe journals with tombstones in the sidecar and `frame_removals` (migration 0008), so sync and uploads never bring them back unless restored or uploaded again on purpose; trash kinds, restore reasons and the `EmptyTrash` job on the desktop's Trash… too (typed entry count); the panel's files revalidated (`no-cache`, ETag); upload from the panel (R3) — file picker or drop, no folders, a self-tested in-house SHA-256 in a module worker, Exif capture time, resumable chunks. Known limitations: a never-hashed photo whose file was already missing is deleted without a tombstone; an unhashed server frame of a photo deleted on a PC stays *missing here* until the server verifies it; `jobState` carries no kind, so panel pages refresh after any job. Phase 4a done and released as `v0.1.0-rc.6` (one adversarial review round and six fix rounds; strings in all 38 languages): Reorganize after import (R7) on the desktop (Archive manager, Library, the toast after Settings › Archive templates change; it replaces Rename… and Move…) and the admin panel (Library, the *Saved* toast of Archive) — folder, file and title templates applied to filed sequences behind a dry run that lists every change, the photos that keep their names and why (in place, never verified, missing) and the sequences that stay whole (unreadable sidecar), applied by the `move` job of exactly the confirmed plan (fingerprint, `POST /api/v1/archive/reorganize`, plans kept a few minutes on the server), which holds the rest when paused, cancelled or failed (also while the archive is offline), lets a sequence still receiving photos keep its file names and takes along a sequence left as it was inside a folder that moves; files renamed in two phases under `.chronos/rename-files.json`, completed after a crash by the next writer; the index, frames and exports follow a moved folder in one transaction, here and at another index's next scan, and writers never create a folder a Reorganize left nor write into one another sequence took; import, upload and Reorganize name photos by one rule (the sequence's camera and lens), and templates follow one set of rules everywhere (no folder scans skip, the extension kept, names that tell photos apart), held only to templates given anew. Known limitations: a reader without the sequence's lease can miss a file while its files are renamed; a change made on disk alone after a server dry run is found by the job, which fails changing nothing; a photo restored from the trash after a Reorganize keeps its old name; a render of another program whose folder moves while it runs is not stopped. Phase 4b done and released as `v0.1.0-rc.7` (one adversarial review round, 42 findings, and three fix rounds; strings in all 38 languages): mass conversion after import (R7) on the desktop (the Archive manager's set, the Library's selection) and the admin panel (the Library's selection) — JPEG with a quality, TIFF-16 or linear DNG (the archival choice, scene-referred so a RAW's highlights above white and colours outside sRGB survive), Replace or New sequence chosen at every run and never remembered, behind a dry run that lists each sequence's photos and sizes, the photos that stay as they are and why (on the server, what it cannot read at full resolution: convert on a PC) and the free space where the conversion writes; Replace confirmed by typing; the `convert` job (stored as 19) converts exactly the photos confirmed (their digest in its parameters, their ids in `journal/convert-.photos`, pinned when it first comes to a sequence; a retried New sequence never makes a second copy), one sequence at a time and all or nothing, resumable through `journal/convert-.*` and `staging/convert-/`, never twice at once; full-resolution decodes with the managed decoders first (never a 16-bit file from an 8-bit RAW development, never a TIFF WIC would read as black or noise), what Chronos reads from a photo never changed (a JPEG or TIFF-16 carries the profile; a linear DNG takes sRGB values only, so Adobe RGB, Display P3, ProPhoto and gamma-1.0 photos go to TIFF-16 or JPEG), Exif carried, every file verified by the server's decoders; Replace swaps the files of the frames in place under `replace.pending.json`, the originals going into a replaced trash entry that the toast's Undo or Restore swaps back and that Empty erases only while the archive on disk shows each conversion intact, or deleted on its own word (a tombstone, the trash, or `trash/.erased/.json`; named first in its confirmation); import still copies byte for byte and the card keeps a converted photo's copy; sync and the ingest count every encoding of a photo as one; `POST /api/v1/archive/convert` in the plan cache Reorganize uses. Known limitations: a photo that fails although its headers read well leaves its sequence as it was; a decode larger than the memory stops the job; a damaged file that still decodes converts as decoded; a read error while a dry run reads a TIFF, DNG or TIFF-based RAW header lists the photo as needing a PC, preview-only or unreadable rather than held (the reader swallows it; nothing beyond the plan converts); JPEG and TIFF-16 clip float values beyond 0..1; not verified: a TIFF whose first image is a thumbnail and whose main image only WIC reads would convert at the thumbnail's size; a PNG's gamma and primaries without a profile count as sRGB; a linear DNG bakes the white balance in and clips below black; the desktop's Undo lives in the job's end toast only (later: Restore). Phase 5a done and released as `v0.1.0-rc.8` (one adversarial review round, 55 findings, and five fix rounds; strings in en and it): the desktop's workspace and projects with this PC's archive as the home (R8) — a sequence's projects (Main, mirrored both ways with the sequence's settings so older clients, analyses and sync keep working, and other named projects), each a linear history of immutable versions in the portable form (positions parked by photo, SHA-256 of canonical text), kept as sidecars in `.chronos/projects/` and indexed by migration 0009 (`projects`, `project_versions`, `renders.project_id`/`project_version_id`), deleted only on the archive's word (the projects' trash read first), healed from the index when a record is lost or behind, one Main decided from the records; Edit opens only workspace projects: *Open in workspace* (project, proxies, copy size and free space), the `workspace-copy` job (stored as 20, desktop only, hash-verified, resumable, space checked, its cancel clean-up under the project's lease), the working state in a folder outside the library, the title's project button (state chip; Save version with Ctrl+S, Sync, History with Compare and Restore, Open, New, Rename, Delete, Remove local copy after a plan), push and pull with replay and field-level merge under crash-safe journals, conflicts only where both sides changed a setting (Keep mine, Take library's, Save both, Later), Update media, newer and damaged copies named and left untouched, renders at the home with the settings embedded, `.chronos` format 2; Settings › Workspace (Folder with Change…, Sync, Kept versions). Known limitations: a server sequence still opens with proxies (the server home is 5b); originals, local render, moving the folder with its projects, emptying `/.trash`, clean-up and the size limit are 5c; a capture still edits the library; nothing restores from the projects' trash yet; a lost record waits 2 minutes of one running Chronos before it is written again. Phase 5b done and released as `v0.1.0-rc.10` on 2026-11-04 (`81c303f4`; one adversarial review round, 21 findings, 19 fixed; strings in all 38 languages): a Chronos Server as the home of its sequences' projects (R8) — `/api/v1/sequences/{sid}/projects` on the archive's `ProjectService` (list with Main made at the first read, create, rename, delete by the owner, the maker or an admin, head, versions in size-capped pages, the stored check, push with its outcome, the frames and their stamp), the `projects` capability and `projectChanged`, Main taking settings written outside the projects soon after (`ProjectCatchUp`), a settings `PATCH` writing `project.json` under the lease, no projects for a sequence without photos, renders and render nodes of a project version, and the admin panel's Projects section (versions, Rename, Delete); on the desktop `ServerProjectHome` through the signed-in session: *Open in workspace* in Edit and on the Server screen, the proxies downloaded into the workspace (hash-checked, resumable, thumbnails standing in while the server has no proxy), push, pull, conflicts, history and the chip against the server (*Server newer*, *Not on server*), renames followed, renders and analyses on the server of the version it holds after *Send and render*; an account without Edit and an older server keep *Open with proxies*. Known limitations: projects read *Offline* when signed in to their server through another address; a copy reads the server's frames in one answer; *History* downloads every version's settings. A final check (2026-11-04) fixed what it left: Main's birth on an upgraded server keeps the settings an earlier release's `PATCH` wrote into the index alone (`IndexSettingsMayLead`), a pull never fails on the name it follows, the Server screen's row actions stay on one line and the capture shows sample paths (16 baselines recaptured: `server-*`, `settings-storage`, `settings-workspace`, `settings-advanced`, `archive-rebuild`). Phase 5c done and released as `v0.1.0-rc.11` on 2026-11-04 (`db389a54`; one adversarial review round, 35 findings, 32 confirmed and fixed, compat-2 in part; a final check fixed one more; strings in all 38 languages): originals in the workspace (R8) — *Open in workspace* › *Originals* (Default media first; sizes also for a server's sequence), *Copy originals…* and *Proxies only…* behind a plan, the copy from either home streamed, hash-checked against the home and resumable, a frame without a usable original keeping its proxy, media index format 2 and project file format 3 while originals are held (older Chronos refuses them); local render (`workspace-render`, stored as 21) from the workspace's originals into `exports/` with the ledger `renders.json`, *Version on render* saving a version first, and *Send render* (`workspace-send`, 22) to this PC's archive (staged, read back, filed under the lease) or to the server (`RenderUploadRequest` with `projectId`/`projectVersionId`, checked against the sequence, 422 `project_mismatch`), idempotent by render id, refusals per render, a version a replay renamed found by its content hash, the Export step's *Not sent* and *Send again*; *Pause metered transfers* holding uploads, the sync's downloads and the workspace's server copies and sends; originals judged by their bytes against the home's frames on removal, clean-up and Proxies only, the rest kept in the workspace's trash (entries filled under `.incoming-` names, emptied only by *Empty…* with the entry count typed and a fingerprint); the clean-up (`WorkspaceCleaner`: projects in step with their home, not open, without jobs or unsent renders; *Clean after* 30 days and *Size limit* 100 GB, the `workspace-cleanup` schedule daily at 04:30 and the limit after each copy); Remove local copy weighing unsent renders and originals; moving the workspace folder (`workspace-move`, 23; `WorkspaceMover`): a plan, renamed on one volume or copied and hash-verified across volumes, the journal `.move.json`, the source kept until the switch, resume and undo, jobs finding their project where the workspace is now (`WorkspaceJobRoots`), *Resume* in Settings; Settings › Workspace complete (Folder with Move…, Size limit, Default media, Sync, Version on render, Kept versions, Clean after, Open project, Trash). Known limitations: an older server drops a render's provenance and the render is still marked sent (logged); an original held open after Proxies only leaves the media index at format 1, so a downgraded 0.1.0-rc.10 could delete it; the removal plan's original count is an estimate and can fail when `media/originals` cannot be read; the Export tab's *Send again* view model has no unit test. | -| 9 Monetization | Not started: requires explicit approval (§22). | +| 8.4 Owner review 4 | In progress (request and plan: `docs/requests/2026-11-06-owner-review-4.md`), one phase released as `v0.1.0-rc.14` with owner review 1 phase 6, then `v1.0.0` (#23): R1 work board of every video made or published, the published apart from workspace work (#29); R2 the anonymous usage counts removed, nothing sent by itself (#30); R3 the archive's whole folder structure created inside the chosen archive path, desktop and server (#31); R4 the repository on Gitea in order (earlier work as closed issues #32–#54 in their milestones, the original documentation in `docs/reference/original`, `fe50b877`); R5 licensing set aside and recorded in #24. Work stops at 75% of the weekly usage. | +| 9 Monetization | Not started: requires explicit approval (§22); the proposal is recorded in issue #24 (owner review 4, R5). | ## Verification (2026-10-12) @@ -155,9 +156,11 @@ The rest of owner review 1, in the owner's order; each phase ends with a release phase's screenshot scenes, `docs/plans/or1-phase-5.md` P8, added and the baselines whose screens changed, such as `edit-export`, captured again and accepted; the PR green on Gitea Actions, squash-merge, tag, the Docker image and the Windows programs) and update the memory notes. -2. Owner review 1, phase 6 (issue #22): Docker, Unraid and deploy docs, BRIEF §24 amendments, full verification; - released as a release candidate. -3. `v1.0.0` (issue #23), the first stable release (owner review 3, R4). +2. Owner review 4 with owner review 1 phase 6 (issues #29, #30, #31, #22): the work board, the usage counts removed, + the archive's folder structure, the deploy guide (`docs/deploy/`, done) and BRIEF §24 (done); full verification; + released as `v0.1.0-rc.14`. +3. `v1.0.0` (issue #23), the first stable release (owner review 3, R4): `:latest` then follows stable releases only, + and the update check offers it to every pre-release build. Phase 8 gate: diff --git a/docs/deploy/README.md b/docs/deploy/README.md new file mode 100644 index 00000000..e764b5df --- /dev/null +++ b/docs/deploy/README.md @@ -0,0 +1,46 @@ +# Deploying Chronos + +How to install, configure, upgrade and back up the Chronos programs. Written for the person who runs them; the +specification behind each behaviour is `docs/BRIEF.md` (§14.9 configuration and Docker, §18 installer and updates, +§19.5 images, §19.6 Unraid template). + +| Guide | For | +|---|---| +| [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 | + +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. + +## The pieces + +| 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 | + +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 +in the database, so back up both (see [docker.md › Backup and restore](docker.md#backup-and-restore)). + +## Where to get them + +| 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) | +| Server image | `gitea.encke-hake.ts.net/balbosoft/chronos-server` — `:latest`, `:`, `: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` | + +While the `BalboSoft` organisation on Gitea is private, downloads, the update check and image pulls work only for +signed-in accounts: run `docker login gitea.encke-hake.ts.net` before pulling. + +## Connecting a client in one paragraph + +Open the admin panel (`http://:/admin`), go to Settings › Network and TLS and copy the **Client +address**. Type it in Chronos (Server) and in the Uploader. The first connection shows the server's certificate +**Fingerprint**; compare it with the one on the same admin page and accept it once. When the container's ports are +published as other host ports, set **Public HTTP port** and **Public HTTPS port** first, so the client address names the +ports clients can reach ([docker.md › Ports](docker.md#ports)). diff --git a/docs/deploy/desktop.md b/docs/deploy/desktop.md new file mode 100644 index 00000000..e59a2722 --- /dev/null +++ b/docs/deploy/desktop.md @@ -0,0 +1,93 @@ +# 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. + +## Downloads + +Each release on Gitea carries: + +| File | What it is | +|---|---| +| `Chronos-Setup-.exe` | Setup with the components Chronos, Uploader and, optionally, Server | +| `Chronos-Uploader-Setup-.exe` | Setup of the Uploader alone | +| `Chronos-win-x64-portable-.zip` | Chronos without installing (portable mode) | +| `Chronos-Server-win-x64-.zip` | Chronos Server for Windows without the setup | +| `SHA256SUMS` | The SHA-256 of every file | + +Check a download before running it: `Get-FileHash .\Chronos-Setup-.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. + +## 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. +- **Silent** (IT deployment): `Chronos-Setup-.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. +- **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. + +## Data folders + +| Install | Settings, index (`chronos.db`), logs, caches | +|---|---| +| Setup | `%LOCALAPPDATA%\Chronos` | +| Portable | `data\` next to `Chronos.exe` | + +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). +Backups of the index go to `backups\` next to it every day (Settings › Advanced › *Back up now* for one more copy; +restore there too). + +## Portable mode + +Unpack `Chronos-win-x64-portable-.zip` into a folder you can write. The `portable.txt` file next to +`Chronos.exe` keeps everything under `data\` in that folder, so the whole folder can move to another PC or a USB drive. +To upgrade, unpack the newer zip over it (or let *Download* fetch it, below); `data\` stays. + +## Updates + +- At start (Settings › Updates › *Check on start*, on by default) Chronos reads the **stable** releases of the releases + 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. +- 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`). +- While the Gitea organisation is private, the check fails for anyone who cannot see the repository (*Check failed*); + it never claims *Up to date* then. + +## Connecting to a server + +In Chronos (Server) and in the Uploader type the **Client address** the admin panel shows (Settings › Network and TLS), +for example `https://nas.local:8444`. An address without scheme or port means port 8443. The first connection shows the +certificate fingerprint: compare it with the admin panel's and accept it once; a later change asks again. An address +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 + +Choose the *Server* component in the setup, or unpack `Chronos-Server-win-x64-.zip` into a folder under +`Program Files`. + +- 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`. diff --git a/docs/deploy/docker.md b/docs/deploy/docker.md new file mode 100644 index 00000000..d6e85a64 --- /dev/null +++ b/docs/deploy/docker.md @@ -0,0 +1,228 @@ +# Chronos Server with Docker + +Chronos Server in a container next to PostgreSQL 17, from `deploy/docker/docker-compose.yml`. For Unraid see +[unraid.md](unraid.md); the settings below are the same there. + +## Install + +```sh +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, PUID/PGID, TZ +docker login gitea.encke-hake.ts.net # while the organisation is private +docker compose up -d +``` + +1. Create the archive folder on the host, owned by `PUID:PGID` (`mkdir -p /srv/timelapse && chown 1000:1000 + /srv/timelapse`). An empty folder, or one owned by root (Docker creates a missing bind source that way), 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 naming it. +2. Open `http://:8080/admin`, sign in as `admin` with `CHRONOS_ADMIN_PASSWORD` and choose a new password (a change + is required at the first sign-in). Without `CHRONOS_ADMIN_PASSWORD` the first start writes a temporary password to + `/data/initial-admin-password.txt`, readable only by its owner, never to the log; the file goes once an + administrator changes their password. Both variables are read only while no administrator exists. +3. In Settings › Network and TLS copy the **Client address** (by default `https://:8443`) into Chronos and the + Uploader, and compare the certificate **Fingerprint** at their first connection. + +`.env` holds the passwords and the host folders: `CHRONOS_ARCHIVE` (archive, default `./archive`), `CHRONOS_DATA` +(`./data`), `CHRONOS_VIDEOS` (videos folder, `./videos`), `CHRONOS_PGDATA` (PostgreSQL's files, `./pgdata`), `PUID`, +`PGID` (default 1000) and `TZ` (default UTC). These four folder names are Compose's, not the server's. + +## Image and tags + +`gitea.encke-hake.ts.net/balbosoft/chronos-server`, built for `linux/amd64`. + +| Tag | What it is | Use it for | +|---|---|---| +| `:latest` | The highest stable release; before the first stable release (`v1.0.0`), the highest pre-release | Production; the compose file and the Unraid template use it | +| `:` (`:1.0.0`, `:0.1.0-rc.14`) | Exactly that release | Pinning, rolling back | +| `:nightly` | `main` as it was at 02:17 that night (version `0.0.0-nightly.`); never a release | Trying what is not released yet; not for production | + +`docker run --rm gitea.encke-hake.ts.net/balbosoft/chronos-server:latest --help` lists every variable the server reads. + +## Volumes + +| Container path | Holds | Required | +|---|---|---| +| `/archive` | The archive: originals, sidecars (`.chronos/` folders), proxies, renders, trash. Readable without Chronos | Yes | +| `/data` | `server.json`, the TLS certificate (`tls/server.pfx`), uploads in progress, logs (`logs/`), `initial-admin-password.txt` | Yes | +| `/videos` | Copies of renders made by *Copy to videos folder* (admin panel › Videos, the desktop's Videos section), flat, hash-checked, " (2)" on a name collision. Chronos never deletes what it copied there | No: with `CHRONOS_VIDEOS_PATH=/videos` | +| `/space` | Read-only view of the volume whose free space the admin panel shows (Unraid's array view) | No: with `CHRONOS_SPACE_PATH=/space` | + +- `/archive` and `/data` are image volumes; `/videos` and `/space` are not, so an image run without them makes no + anonymous volume. A `/videos` that is not a mounted volume, or that `PUID:PGID` cannot write, only warns at start: + copying then fails with its reason in the admin panel, and everything else runs. +- The videos folder must lie outside the archive and the data folder; the admin panel refuses another, and a copy then + answers `videos_folder_invalid`. Remove `CHRONOS_VIDEOS_PATH` and the volume to turn copying off. +- The server writes into the archive's `.chronos` folders at once (staging, trash, locks). One left to root (an + earlier run as root, a copy made as root) stops the start with an error naming it; fix it on the host with + `chown -R : /.chronos`. Nothing inside the archive is ever chowned by the container. + +## Environment variables + +Every server setting comes from, in order: its default, `/data/server.json`, then the environment. **A variable that is +set fixes its setting:** the admin panel shows the field read-only and its tooltip names the variable. Leave a +variable unset to choose the value in the admin panel while the server runs. A value out of range stops the start +with a message naming the variable. + +| Variable | Default | Meaning | +|---|---|---| +| `CHRONOS_DATA_PATH` | `/data` (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 | +| `CHRONOS_SERVER_NAME` | `Chronos Server` | Name shown to clients and announced on the LAN | +| `CHRONOS_ADMIN_USER` | `admin` | First administrator, created only while none exists (letters, digits, `.`, `-`, `_`) | +| `CHRONOS_ADMIN_PASSWORD` | unset: a temporary password in `/data/initial-admin-password.txt` | Its first password; a change is required at the first sign-in | +| `CHRONOS_DB` | `postgres` (Windows: `sqlite`) | `postgres`, `sqlite` (Windows only) or a full connection string (`Host=…;Port=…;Database=…;Username=…;Password=…`), which wins over the parts below | +| `CHRONOS_DB_HOST` | `postgres` | PostgreSQL host | +| `CHRONOS_DB_PORT` | `5432` | PostgreSQL port | +| `CHRONOS_DB_NAME` | `chronos` | Database, owned by the user below | +| `CHRONOS_DB_USER` | `chronos` | PostgreSQL role | +| `CHRONOS_DB_PASSWORD` | unset | Its password (SCRAM, MD5, cleartext and trust are understood) | +| `CHRONOS_DB_SSLMODE` | `prefer` | `disable`, `prefer`, `require` or `verify-full` | +| `CHRONOS_HTTP_PORT` | `8080` | Port the server listens on for HTTP. In a container (the image sets it) only this variable changes it, which matters only with host networking | +| `CHRONOS_HTTPS_PORT` | `8443` | Port the server listens on for HTTPS; as above | +| `CHRONOS_PUBLIC_HTTP_PORT` | unset: the HTTP port | Host port clients use for HTTP when the container's 8080 is published as another; LAN discovery announces it | +| `CHRONOS_PUBLIC_HTTPS_PORT` | unset: the HTTPS port | Host port clients use for HTTPS: the port of the client address, of the admin panel's redirect to HTTPS and of LAN discovery | +| `CHRONOS_TLS_MODE` | `auto` | `auto` (self-signed, made at first start), `pem` (your certificate) or `proxy` (plain HTTP behind a TLS-terminating reverse proxy) | +| `CHRONOS_TLS_CERT` | unset | `pem` mode: path of the certificate (PEM, full chain) inside the container | +| `CHRONOS_TLS_KEY` | unset | `pem` mode: path of its private key (PEM) | +| `CHRONOS_TRUSTED_PROXIES` | `127.0.0.0/8, ::1/128` | `proxy` mode: addresses or CIDR networks of the proxies whose `X-Forwarded-*` headers count; see [TLS](#tls) | +| `CHRONOS_LANG` | `en` | Language of the server's messages when the client's own language is not one Chronos ships | +| `CHRONOS_PARALLELISM` | half the logical cores (1–64) | Photos the running job processes at once; jobs run one at a time. `CHRONOS_WORKERS`, its former name, still sets it with a warning | +| `CHRONOS_PRIORITY_QUEUE` | `false` | `true`: a job of a higher kind pauses the running one, which resumes by itself afterwards | +| `CHRONOS_DISCOVERY` | `true` | LAN discovery beacon (UDP); it leaves a container only with host networking | +| `CHRONOS_LOG_LEVEL` | `Information` | `Trace`, `Debug`, `Information`, `Warning`, `Error`, `Critical` or `None` (also `info`, `warn`, `off`): the log files' and the console's level, locking both | +| `CHRONOS_LOG_CONSOLE_LEVEL` | the log level | The console's (the container log's) level alone; wins over `CHRONOS_LOG_LEVEL` for the console | +| `CHRONOS_LOG_RETENTION_DAYS` | `14` (1–3650) | Days log files in `/data/logs` are kept | +| `CHRONOS_LOG_MAX_FILE_MB` | `50` (0–10240, 0 = no limit) | Size at which a log file continues in `.1.log`, `.2.log`… | +| `CHRONOS_LOG_MAX_TOTAL_MB` | `1024` (0–1048576, 0 = no limit) | Size of all log files together; the oldest go beyond it, never the current one | +| `CHRONOS_LOG_ROTATION` | `daily` | `daily` or `hourly` log files (UTC): `server-yyyyMMdd.log` | +| `CHRONOS_AUDIT_RETENTION_DAYS` | `0` = forever (0–3650) | Days of audit log the *Audit log clean-up* schedule keeps; set, it is applied to that schedule at every start | +| `CHRONOS_DIAGNOSTICS_LOG_MB` | `4` (1–1024) | MB from the end of each log file in the diagnostics zip (admin panel › Logs › *Diagnostics*) | +| `PUID` / `PGID` | `1000` / `1000` | User and group the server runs as; the data folder is given to them | +| `TZ` | `UTC` | Time zone of the schedules and of the folders of photos without a capture time; logs stay in UTC | + +## Ports + +The server listens on **8080** (HTTP: admin panel and API) and **8443** (HTTPS: the API Chronos and the Uploader use) +inside the container. Those two stay as they are on a bridge network: the admin panel shows them read-only, and a value +`server.json` held for them is ignored with a warning and removed at the next save. The **public ports** are the host +ports clients reach. + +| Situation | Compose `ports` | Public ports | Clients use | +|---|---|---|---| +| Default | `"8080:8080"`, `"8443:8443"` | leave empty | `https://:8443` | +| Another service uses 8080 and 8443 on the host (the owner's Unraid case) | `"8087:8080"`, `"8444:8443"` | Public HTTP port **8087**, Public HTTPS port **8444** | `https://:8444`; admin panel `http://:8087/admin` | +| Host networking (`network_mode: host`) | none (ignored) | leave empty | `https://:8443`, or the port set with `CHRONOS_HTTPS_PORT` | + +- Keep the container side of a mapping (after the colon) at 8080 and 8443. Change only the host side, then enter the + same host ports as **Public HTTP port** and **Public HTTPS port** in Settings › Network and TLS, or set + `CHRONOS_PUBLIC_HTTP_PORT` / `CHRONOS_PUBLIC_HTTPS_PORT` (which then lock them). They apply at once: the client + address, the redirect to HTTPS and LAN discovery name the ports clients can reach. +- An address typed in a client without a scheme or port (`nas.local`) means port 8443; `https://nas.local` alone means + 443 (a reverse proxy). Type the client address as the admin panel shows it. +- LAN discovery reaches clients only with host networking: on a bridge network its broadcasts stay inside Docker, and + clients type the client address. With host networking the port mappings do nothing, the server listens on the host's + 8080 and 8443 itself and does not start when another service already uses either: set `CHRONOS_HTTP_PORT` / + `CHRONOS_HTTPS_PORT` to free ports and leave the public ports empty. The name `postgres` no longer resolves there: + publish PostgreSQL on loopback (`ports: ["127.0.0.1:5432:5432"]` under `postgres`) and set `CHRONOS_DB_HOST: + 127.0.0.1`. + +## TLS + +| Mode | What happens | Clients | +|---|---|---| +| `auto` (default) | A self-signed certificate is made at first start in `/data/tls/server.pfx`, valid five years, made anew 30 days before it expires; its SHA-256 fingerprint is logged and shown in Settings › Network and TLS › **Fingerprint** | Trust on first use: the client shows the fingerprint once; compare it with the admin panel's | +| `pem` | Your certificate and key: mount them read-only (`./certs:/certs:ro`) and set `CHRONOS_TLS_CERT=/certs/fullchain.pem`, `CHRONOS_TLS_KEY=/certs/privkey.pem`, readable by `PUID:PGID`. Restart after renewing them | A certificate a public CA signed is trusted at once | +| `proxy` | Plain HTTP on 8080 behind a reverse proxy that terminates TLS | `https://` | + +- The fingerprint changes when `/data` is lost or the self-signed certificate is renewed: clients then ask again. + Compare before accepting; keep `/data` in the backup so it does not change by surprise. +- An address that answers but is not Chronos (another service on that port) is reported as *not a Chronos server*, and + its certificate is never offered for trust. +- Behind a proxy only the proxies listed in `CHRONOS_TRUSTED_PROXIES` may set `X-Forwarded-*` headers; by default only + loopback, since other machines on the LAN reach the HTTP port directly and must not choose the address the sign-in + limit and the audit log see. Give a proxy container a fixed address on a user-defined network it shares with + Chronos (`ipv4_address` in compose, *Fixed IP address* on Unraid), list that address (`172.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`). A proxy on the Docker host itself: run Chronos with host networking. The + admin panel shows *Not via proxy* when a page did not come through a trusted proxy over HTTPS. + +## PostgreSQL + +Chronos Server on Linux needs PostgreSQL 16 or 17 (`CHRONOS_DB=sqlite` is Windows only). The compose file runs the +official `postgres:17` image with its files in `CHRONOS_PGDATA`, and waits for it to be healthy; the server retries the +connection for about 30 seconds more before it stops. + +To use an existing PostgreSQL instead, remove the `postgres` service and `depends_on`, create a role and a database it +owns (`CREATE ROLE chronos LOGIN PASSWORD '…'; CREATE DATABASE chronos OWNER chronos;`) and set `CHRONOS_DB_HOST`, +`CHRONOS_DB_PORT`, `CHRONOS_DB_NAME`, `CHRONOS_DB_USER`, `CHRONOS_DB_PASSWORD` and, for a remote one, `CHRONOS_DB_SSLMODE=require` +or `verify-full`. Or give a whole connection string in `CHRONOS_DB`. + +## Upgrading + +1. Back up first: at least the database and `/data` ([below](#backup-and-restore)). +2. `docker compose pull && docker compose up -d`. +3. The server migrates the database at start; the log shows `Database Postgres ready, schema version N`. Jobs in + progress resume from their last checkpoint. + +- Migrations only go forward. An older image refuses a database a newer one migrated (*the database schema version … + is newer than the version … this build supports*): to go back, restore the database backup taken before the upgrade, + then run the older tag. +- Stay on `:latest` (or a pinned `:`) in production. A container on `:nightly` runs unreleased code: move it to + `:latest` by editing the image tag, after a backup. +- Release notes list upgrade steps when a release needs one (a variable renamed, a template field added). Earlier + compose files and templates set `CHRONOS_LOG_LEVEL: Information`, which now locks both log levels: delete the line to + choose them in the admin panel. + +## Backup and restore + +| Part | Holds | How | +|---|---|---| +| Archive (`/archive`) | Photos, sidecars, projects, proxies, renders, the trash | Your usual file backup (rsync, snapshots, Unraid's tools). Include every `.chronos` folder | +| 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 | + +Back up (the server stopped, so nothing changes while the dump runs): + +```sh +docker compose stop chronos +docker compose exec -T postgres pg_dump -U chronos -d chronos -Fc > chronos-$(date +%F).dump +sudo tar -czf chronos-data-$(date +%F).tgz data +docker compose start chronos +``` + +Restore into the same or a new host (the same image tag, or a newer one): + +```sh +docker compose down +sudo tar -xzf chronos-data-.tgz # puts ./data back +docker compose up -d postgres +docker compose exec -T postgres pg_restore -U chronos -d chronos --clean --if-exists < chronos-.dump +docker compose up -d +``` + +Put the archive back at the same `CHRONOS_ARCHIVE` path before the last step. After restoring an older database next to +a newer archive, run Archive › *Scan* so the index catches up with what the archive holds. + +## Troubleshooting + +| Symptom | Cause and fix | +|---|---| +| The Uploader or Chronos cannot connect | The client uses a port the host does not publish. Copy the **Client address** from Settings › Network and TLS; when host ports are not 8080/8443, set **Public HTTP port** and **Public HTTPS port** to them first ([Ports](#ports)) | +| *Not a Chronos server* | Another service answers on that host port (on the owner's host 8443 is another service). Use the client address with the right public HTTPS port | +| The free space shown is the cache's (Unraid) or too small | A cached share reports its primary storage. Map the share's array view read-only to `/space` and set `CHRONOS_SPACE_PATH=/space` ([unraid.md](unraid.md#free-space-of-the-array)) | +| The container restarts at once, log: *… is not writable by PUID:PGID* | Give that user write access to the archive (or the named `.chronos` folder) on the host, or set `PUID`/`PGID` to its owner | +| Log: *Database not reachable yet … retry* | PostgreSQL is starting, or `CHRONOS_DB_HOST` is wrong. Container names resolve only on a shared user-defined network; on Unraid's default bridge use the host's IP | +| A field in the admin panel is read-only | A variable sets it; its tooltip names it. Remove the variable to change it in the panel | +| The client asks to trust a new fingerprint | `/data` was replaced or the self-signed certificate was renewed. Compare with the admin panel before accepting | +| Clients do not find the server by themselves | LAN discovery needs host networking; type the client address instead | +| *Copy to videos folder* fails (`videos_folder_unset`, `videos_folder_invalid`) | Map a host folder outside the archive to `/videos` and set `CHRONOS_VIDEOS_PATH=/videos` | +| `docker pull` asks for credentials | The organisation is private: `docker login gitea.encke-hake.ts.net` | +| Host networking: the server does not start, port in use | Set `CHRONOS_HTTP_PORT` / `CHRONOS_HTTPS_PORT` to free ports | + +For a bug report attach the server's diagnostics zip (admin panel › Logs › *Diagnostics*): logs, a system report, the +settings and recent failed jobs, never photos, passwords or tokens. You download it; it goes nowhere by itself. diff --git a/docs/deploy/unraid.md b/docs/deploy/unraid.md new file mode 100644 index 00000000..08dc71a9 --- /dev/null +++ b/docs/deploy/unraid.md @@ -0,0 +1,124 @@ +# Chronos Server on Unraid + +Chronos Server from the template `deploy/unraid/chronos.xml`, next to the official PostgreSQL template. Every variable +and behaviour is described in [docker.md](docker.md); this page covers what is particular to Unraid. + +## Install + +1. **PostgreSQL.** Install the official **postgresql17** template from Community Applications (16 works too). Create a + role and a database for Chronos: + + ```sh + docker exec -it postgresql17 psql -U postgres \ + -c "CREATE ROLE chronos LOGIN PASSWORD ''" \ + -c "CREATE DATABASE chronos OWNER chronos" + ``` + +2. **The template.** Unraid's *Template repositories* read GitHub and GitLab addresses, not Gitea's, so save the template + as a user template from the Unraid terminal: + + ```sh + wget -O /boot/config/plugins/dockerMan/templates-user/my-chronos-server.xml \ + https://gitea.encke-hake.ts.net/BalboSoft/Chronos/raw/branch/main/deploy/unraid/chronos.xml + ``` + + While the `BalboSoft` organisation is private, the download and the image pull need an account: download the file + in a signed-in browser and copy it there, and run `docker login gitea.encke-hake.ts.net` once in the terminal. +3. **The container.** Docker › *Add container* › Template › *chronos-server*. Fill in at least: + + | Field | Value | + |---|---| + | Admin password | The first password of `admin`; a change is required at the first sign-in | + | Database host | The Unraid server's IP address (the PostgreSQL template publishes 5432). A container name resolves only when both containers are on the same custom Docker network, never on the default *bridge* | + | Database password | The role's password from step 1 | + | Archive | The share of your time-lapses, default `/mnt/user/Timelapse` | + | Array view | The same share under `/mnt/user0`, default `/mnt/user0/Timelapse` (see [free space](#free-space-of-the-array)) | + + Leave the network type on *Bridge* unless you need LAN discovery ([below](#network-type)). +4. **First sign-in.** Open the WebUI (`http://[IP]:[HTTP port]/admin`), sign in as `admin` and choose a new password. +5. **Clients.** In Settings › Network and TLS copy the **Client address** into Chronos and the Uploader and compare the + **Fingerprint** at their first connection. + +## Template fields + +| Field | Container side | Default | Notes | +|---|---|---|---| +| HTTP port | port 8080 | 8080 | Admin panel and API over HTTP; the WebUI link follows it | +| HTTPS port | port 8443 | 8443 | API over TLS for Chronos and the Uploader | +| Public HTTP port | `CHRONOS_PUBLIC_HTTP_PORT` | empty | The HTTP port above when it is not 8080 | +| Public HTTPS port | `CHRONOS_PUBLIC_HTTPS_PORT` | empty | The HTTPS port above when it is not 8443: the port of the client address | +| Archive | `/archive` | `/mnt/user/Timelapse` | Originals, sidecars, proxies, renders | +| Array view | `/space` (read-only) | `/mnt/user0/Timelapse` | Optional; with *Space path* | +| Videos | `/videos` | empty | Optional folder for *Copy to videos folder*, not inside the archive (for example `/mnt/user/Videos/Chronos`); with *Videos path* | +| App data | `/data` | `/mnt/user/appdata/chronos` | Settings, TLS certificate, uploads in progress, logs | +| Admin user / Admin password | `CHRONOS_ADMIN_USER` / `CHRONOS_ADMIN_PASSWORD` | `admin` / empty | Read only while no administrator exists | +| Database host, port, name, user, password, TLS | `CHRONOS_DB_*` | —, 5432, `chronos`, `chronos`, —, `prefer` | Port and TLS are advanced | +| Videos path | `CHRONOS_VIDEOS_PATH` | empty | `/videos` once *Videos* is mapped; empty turns copying off unless a folder is set in the admin panel | +| TLS mode, Trusted proxies, Space path, Server name, Parallelism, Priority queue, the log fields, Audit retention, Diagnostics log size, PUID (99), PGID (100), Time zone | the variables of [docker.md](docker.md#environment-variables) | as there | Advanced. Empty means the admin panel chooses; a value locks the setting there | + +The template has no field for `CHRONOS_TLS_CERT`, `CHRONOS_TLS_KEY`, `CHRONOS_LANG`, `CHRONOS_DISCOVERY`, +`CHRONOS_HTTP_PORT` or `CHRONOS_HTTPS_PORT`: add them with *Add another Path, Port, Variable…* › *Variable* when +needed. + +## Ports other than 8080 and 8443 + +When another container already uses 8080 or 8443 on the Unraid host, change only the host side and tell Chronos which +ports clients use. The owner's setup: + +| Field | Value | +|---|---| +| HTTP port | **8087** (container 8080) | +| HTTPS port | **8444** (container 8443) | +| Public HTTP port | **8087** | +| Public HTTPS port | **8444** | + +Clients then connect to `https://:8444`, the client address the admin panel shows, and the WebUI opens +`http://:8087/admin`. The admin panel's *HTTP port* and *HTTPS port* stay 8080 and 8443, read-only: they are +the container's ports, not the ones clients use. The public ports may be left empty in the template and entered in the +admin panel's Settings › Network and TLS instead; set in the template, they are locked there. + +## Free space of the array + +A user share (`/mnt/user/`) reports the free space of its primary storage, often the cache, while the mover +sends the photos to the array. The **Array view** maps the same share as seen on the array alone (`/mnt/user0/`) +read-only to `/space`, and *Space path* `/space` makes the admin panel show that volume's free space. When the archive's +own volume differs it shows apart as *Write volume*. Change *Array view* together with *Archive*, or remove it and clear +*Space path*. Uploads still check the archive's own volume. + +## Network type + +- **Bridge** (default): the port mappings apply, LAN discovery stays inside Docker, clients type the client address. +- **Host**: clients find the server by themselves, the mappings are ignored and the server listens on the host's 8080 + and 8443 itself; it does not start when another service uses either. Add the variable `CHRONOS_HTTP_PORT` or + `CHRONOS_HTTPS_PORT` with a free port first and leave the public ports empty. +- A **custom Docker network** shared with the PostgreSQL container lets *Database host* be the container's name. + +## Upgrading + +1. Back up `/mnt/user/appdata/chronos` and the database ([below](#backup)). +2. Docker › the container › *Check for updates* / *Update*, or *Force update*. The database is migrated at start; jobs + resume from their last checkpoint. + +A container made from an earlier template, or one on `:nightly`: edit it, set *Repository* to +`gitea.encke-hake.ts.net/balbosoft/chronos-server:latest`, and when its host ports are not 8080/8443 add the public +ports (*Public HTTP port* 8087 and *Public HTTPS port* 8444 in the owner's case), or enter them in the admin panel. An +earlier template's *Log level* `Information` now locks both log levels: clear it to choose them in the admin panel. +Going back to an older tag needs the database backup taken before the upgrade (migrations only go forward). + +## Backup + +- **App data and PostgreSQL**: the *Appdata Backup* plugin, with both containers stopped during the backup, covers + `/mnt/user/appdata/chronos` and the PostgreSQL template's data folder. Or dump the database yourself: + `docker exec postgresql17 pg_dump -U chronos -d chronos -Fc > /mnt/user/backups/chronos-$(date +%F).dump`. +- **Archive**: the share itself, with your usual share backup; include the `.chronos` folders. +- **Restore**: put the app data and the archive back, recreate the container from the template with the same paths, + restore the dump (`docker exec -i postgresql17 pg_restore -U chronos -d chronos --clean --if-exists < `), + then start Chronos. See [docker.md › Backup and restore](docker.md#backup-and-restore) for what each part holds. + +## Troubleshooting + +See [docker.md › Troubleshooting](docker.md#troubleshooting). The two Unraid classics: + +- **The Uploader cannot connect**: the host ports differ from 8080/8443 and the public ports are empty, so the client + address names ports the host does not publish. Set *Public HTTP port* and *Public HTTPS port*. +- **The free space shown is the cache's**: map *Array view* and set *Space path* `/space`. diff --git a/docs/requests/2026-10-15-owner-review-1.md b/docs/requests/2026-10-15-owner-review-1.md index e6f8b9a7..91294582 100644 --- a/docs/requests/2026-10-15-owner-review-1.md +++ b/docs/requests/2026-10-15-owner-review-1.md @@ -63,6 +63,6 @@ | 3b | R7 Edit section ("Sequenza" → "Modifica"), sequence picker, guided path from analysis to export | done 2026-10-16: BRIEF §4.1, §10.2, §12.1, §12.3, §24; four DECISIONS rows (the rename, the path, the step rules, the picker); DESIGN §4 step bar and §7; `Editor.html` with the step bar and every mockup's rail label; `i18n/GLOSSARY.md` and the 36 language glossaries (Edit, Path, Step, Findings); the new strings in all 38 languages | `5aeb6aa` | | 4 | R5 visual crop, proportions win; R6 transforms, straighten, colour filters | done 2026-11-04, released as `v0.1.0-rc.12` (issue #19; one adversarial review round, 30 findings, all confirmed and fixed, and a final check that fixed one more; strings in all 38 languages; 31 screenshot baselines accepted; the line-end fix of issue #20 on the way): BRIEF §10.3, §11.2, §11.4, §12.3, §14.3, §14.7, §24; 32 DECISIONS rows dated 2026-11-04 (conditional settings format and the rule for future members; orientation members and order; the cover zoom; crop coordinates; the locked crop; a quarter turn keeps the content; proportions win, also for an advised aspect, not format-gated in storage; routing format and the server's announcement; the colour look and its values; no ninth step; raw thumbnails; Source framing; global only; the compatibility matrix; groundwork details; crop values; the advisor on the view; routing errors; encoder limits either way round; desktop gates; the crop on the preview; Camera, Look and Export rows; visuals; strings, icons and captures; the review's routing, gates and editing fixes); CHANGELOG [Unreleased] with the upgrade note and the known limitations, and the 5c entries under [0.1.0-rc.11]; ARCHITECTURE geometry, colour, render size and format, gates; DESIGN setting rows, crop overlay and icons; STATUS 8.1 | `188b2c2e` | | 5 | R3 export panel and Render menu; R8 export options; R9 videos library (desktop, server API, admin page, copy folder, trash) | done 2026-11-05, to be released as `v0.1.0-rc.13` (issue #21; plan `docs/plans/or1-phase-5.md`; groundwork, seven parallel parcels and an integration, then one adversarial review round whose findings are all fixed; strings in English and Italian, the other 36 languages imported before the release): BRIEF §5, §7, §11.1, §11.3, §11.4, §11.5, §12.1, §12.3, §12.5, §12.8, §12.10 (new: Videos), §14.3, §14.6, §14.7, §14.8, §14.9, §19.6, §24; 41 DECISIONS rows dated 2026-11-05 (the plan's 22 decisions and the open questions' defaults; groundwork contracts; workspace stills and sync hashes; the review's trash moves, free names, routing floor, encoder warnings and Videos layout; fades limited together, the hold in whole periods, still contents and 16-bit TIFF; the server videos folder and Docker choices; the copy priority; batch playback routing; the desktop Videos section's choices; the trash entry title; the Export step and Render menu details); CHANGELOG [Unreleased] with the upgrade note (shortcuts, settings format 3, older nodes, `CHRONOS_VIDEOS_PATH`, `/videos`) and the known limitations, and the phase 4 entries under [0.1.0-rc.12]; ARCHITECTURE output program, still, videos library, trash area, copy job, Videos section and endpoints; DESIGN collapsible groups, preset table, two-line menu entries, Videos; mockups `Export.html` (new layout and the Render menu), `Videos.html`, `AdminVideos.html` and the Videos rail entry; STATUS 8.1 | this PR | -| 6 | Docker/Unraid/deploy docs, BRIEF §24 amendments, full verification | todo | | +| 6 | Docker/Unraid/deploy docs, BRIEF §24 amendments, full verification | in progress 2026-11-06, with owner review 4 (`docs/requests/2026-11-06-owner-review-4.md`), to be released as `v0.1.0-rc.14` (issue #22): the deploy guide `docs/deploy/` (README, `docker.md`, `unraid.md`, `desktop.md`); BRIEF §14.9, §19.6, §24 (every amendment since owner review 1 listed); full verification before the release | | Each phase updates BRIEF (amended paragraphs), DECISIONS, CHANGELOG, STATUS and this file before its commit. diff --git a/docs/requests/2026-11-04-owner-review-3.md b/docs/requests/2026-11-04-owner-review-3.md index 197198fd..df1ebe8a 100644 --- a/docs/requests/2026-11-04-owner-review-3.md +++ b/docs/requests/2026-11-04-owner-review-3.md @@ -44,4 +44,4 @@ Two screenshots came with it: the Unraid template (repository `chronos-server:ni |---|---|---|---| | 1 | R1 ports, R2 baselines | done 2026-11-04, released as `v0.1.0-rc.9` (one review round with two reviewers and a checker; strings in all 38 languages): BRIEF §12.7, §14.8, §14.9, §19.6; DECISIONS rows dated 2026-11-04 (public ports as settings, the settings DTO members, the container port lock, saved listening ports removed, the client address, one address rule, the Chronos identity checks, the HTTP port typed as HTTPS, the zone index, Host networking, baselines from the development PC, fixed capture values); CHANGELOG [Unreleased] with the Unraid upgrade note | `255e1490` | | 2 | R4 owner review 2 phases 5b and 5c | done 2026-11-04: 5b released as `v0.1.0-rc.10` (`81c303f4`), 5c as `v0.1.0-rc.11` (`db389a54`) | `81c303f4` (5b), `db389a54` (5c) | -| 3 | R4 owner review 1 phases 4–6, then `v1.0.0` | in progress: phase 4 done 2026-11-04, released as `v0.1.0-rc.12` (issue #19, `188b2c2e`); phase 5 done 2026-11-05, to be released as `v0.1.0-rc.13` (issue #21); phase 6 (#22) and `v1.0.0` (#23) todo | `188b2c2e` (phase 4) | +| 3 | R4 owner review 1 phases 4–6, then `v1.0.0` | in progress: phase 4 done 2026-11-04, released as `v0.1.0-rc.12` (issue #19, `188b2c2e`); phase 5 done 2026-11-05, to be released as `v0.1.0-rc.13` (issue #21); phase 6 (#22) in progress for `v0.1.0-rc.14` with owner review 4 (2026-11-06); `v1.0.0` (#23) todo | `188b2c2e` (phase 4) | diff --git a/docs/requests/2026-11-06-owner-review-4.md b/docs/requests/2026-11-06-owner-review-4.md new file mode 100644 index 00000000..eed05231 --- /dev/null +++ b/docs/requests/2026-11-06-owner-review-4.md @@ -0,0 +1,44 @@ +# Owner review 4 (2026-11-06) + +## Owner's text (verbatim, Italian) + +> Lasciamo un attimo da parte la questione delle licenze ma segnati quello che mi hai detto in un lavoro o un progetto +> perchè sarà da implementare. +> +> Metti a posto la repository su Gitea inserendo anche i lavori vecchi e la documentazione iniziale con gli sceen. +> Puoi trovare la documentazione originale in "A:\Download\files.zip". +> +> Inoltre aggiungi questee modifiche: +> +> * aggiungi anche un parte che permette di avere un elenco di tutti i video creati e/o pubblicati, separando +> pubblicazione da area di lavoro come se fosse una bacheca del lavoro svolto +> * togli l'invio di dati di diagnostica per migliorare il programma. Non lo voglio (anche perchè non saprei dove +> inviare i dati) +> * nel percorso che viene passato come percorso dell'archivio assicurati di creare al suo interno tutta la struttura +> di cartelle proprie dell'archivio (sia che sia in docker sul server sia che si su windows) +> +> Riprendi la fase 6 e v1.0.0. +> Fermati al 75% dell'uso settimanale. + +## Interpretation + +| Id | Request | Working interpretation | +|---|---|---| +| R1 | A board of the work done (issue #29) | One list of every video made or published, the published ones (in the library, on this PC's archive or the server) apart from the work still in a workspace, like a board of finished work: the desktop's Videos section and the admin panel's Videos page. | +| R2 | No diagnostic data sent (issue #30) | The only data Chronos could send by itself is the anonymous usage counts (Settings › General › *Send anonymous counts*, the consent of BRIEF §21): removed with their setting and strings. The diagnostics zip stays: the user saves it by hand and attaches it to a bug report if they choose; it is never sent. | +| R3 | The archive's folder structure inside the archive path (issue #31) | When an archive path is chosen or the server starts on one (the desktop on Windows, the server in Docker or on Windows), Chronos creates the archive's whole structure inside it at once (`.chronos/` with `archive.json` and its folders), rather than folder by folder as work first needs them. | +| R4 | Put the Gitea repository in order | The earlier work recorded on Gitea as closed issues (#32–#54, one per phase or fix, each in its release's milestone, `v0.1.0-rc.1` … `v0.1.0-rc.11`); the original documentation of `files.zip` (the first brief, design kit, screen mockups and icon sheet, then named Titano) kept frozen under `docs/reference/original` (`fe50b877`). | +| R5 | Licensing set aside, recorded | The business model and licensing proposed in owner review 3 (R5) recorded in issue #24 (milestone `v1.0.0`), to be implemented later; Phase 9 (BRIEF §21, §22) still waits for the owner's explicit approval. | +| R6 | Resume phase 6 and `v1.0.0` | Owner review 1 phase 6 (issue #22: the Docker, Unraid and deploy guide, BRIEF §24, full verification) together with R1–R3 in `v0.1.0-rc.14`, then `v1.0.0` (issue #23). Work stops at 75% of the weekly usage (the rule was 60%). | + +## Questions and answers + +None asked: R1–R3 follow the owner's words and earlier answers (owner review 1: one videos library, desktop and server). +The owner corrects an interpretation at the next review. + +## Delivery plan + +| Phase | Content | State | Commit | +|---|---|---|---| +| 1 | R1 work board (#29), R2 usage counts removed (#30), R3 archive folder structure (#31); R4 repository; R5 #24; owner review 1 phase 6 (#22): `docs/deploy/` (Docker, Unraid, desktop), BRIEF §14.9, §19.6, §24 | in progress, to be released as `v0.1.0-rc.14` | | +| 2 | `v1.0.0` (#23), the first stable release (owner review 3, R4) | todo | |