Implement manual versioned Synology deployments for S6

docs/s6-validation.md

@@ -0,0 +1,107 @@
+# S6 implementation and operational evidence
+
+Status: IN_PROGRESS. Repository implementation and local validation do not yet
+establish an operational Synology deployment. No production release tags have
+been created by this implementation session.
+
+## Confirmed environment
+
+- Work is on `feature/S6_deployment`.
+- Read-only authenticated inspection of the installed Gitea confirmed run fields
+  `path=build.yaml@refs/heads/main`, `status=completed`, `conclusion=success`,
+  `event=push`, `head_branch=main` and `head_sha`.
+- No remote Git tags existed at the time of that read-only inspection.
+- The maintainer created the dedicated DSM account `agiledancers-deploy` and
+  confirmed SSH port 22. A separate Ed25519 deployment key was generated outside
+  Git on the mini-pc and installed on the NAS.
+
+Subsequent live checks confirmed key-based access after removing group/other
+write permissions from the account home. The maintainer installed the dedicated
+Docker sudo rule using `deploy/enable-docker.sh`; a subsequent noninteractive
+check reports `linux/x86_64`. NAS model is **DS224+**, Compose is
+**v2.20.1-6047-g6817716**, `timeout -k` and `curl` are available, and port **8088**
+was free. The daemon allows HTTP registry access only through `127.0.0.0/8`.
+Deployment therefore uses the NAS-local `127.0.0.1:3000` alias of the same Gitea
+registry, without restarting Gitea/Kimai or changing the shared Docker daemon.
+
+## NAS setup and real image preparation
+
+`java ci/Ci.java configure-deployment` succeeded using separate owner-only local
+pull/release tokens. It provisioned `/volume1/docker/agiledancers-production`,
+the private IP/port configuration and registry pull login, verified the real NAS
+preflight, and stored the three deployment secrets and five variables in Gitea.
+No secret values are recorded here.
+
+A real preparation probe exercised the production coordinator/API/SSH adapter
+and NAS script, stopping explicitly at the tag-creation boundary. It retrieved
+both images for verified main commit
+`b1544357bf6ea5e1607e1de1fa4872b9510690a8` (Gitea API build run ID **35**), verified
+revision/platform labels, selected registry digests and passed Compose v2.20
+configuration validation. It released the deployment lock without creating a
+Git tag, pending journal, successful release state or application containers.
+The displayed candidate `v1.0.0` was not allocated as a release.
+
+| Component | Retrieved digest (NAS registry alias `127.0.0.1:3000/wanjakrah/`) |
+| --- | --- |
+| Backend | `sha256:d46af705c527a8eaa506407206cfce927edbc4b774951cf13da8702b5cb8c56d` |
+| Frontend | `sha256:d6c09ad839b929591878195c7403cbf0bbf24ac6e8d335ef90d72b7982c4ba31` |
+
+Local probe evidence: `ci/artifacts/deployment/setup.log`, `nas-image-probe.log`
+and `nas-image-probe.json` (ignored by Git). Retained configuration on the NAS:
+`releases/image-probe-bbb2a980-e624-4331-adb6-b8fffd51fa5d/`. This is preparation
+evidence, not a successful production release or Gitea dispatch run.
+
+## Local checks
+
+- `java ci/Ci.java test`: **17 passed**, including publication gates and process
+  deadlines.
+- `java ci/Ci.java release-test`: **32 passed**, including all version increments,
+  input/main/manual gates, verified-build provenance, digest preparation failures,
+  duplicate/stale release rejection, retry, version high-watermark after rollback,
+  automatic recovery, failed recovery/first release, ambiguous state commits,
+  lock contention, annotated-tag identity and registry aliases.
+- Seven of those release tests execute the actual POSIX NAS script against
+  disposable command adapters, covering image/platform checks, published endpoint
+  requests, retained-configuration mismatch, bounded readiness failure, overlapping
+  replacement fencing and atomic state/journal handling. These are simulated
+  failure-path tests, separate from the real NAS preparation probe above.
+- `sh -n` passed separately for `deploy/remote.sh`, `deploy/provision.sh` and
+  `deploy/enable-docker.sh`.
+- `mvn -N -Dformat.mode=check exec:exec@format`: passed with no differences.
+- All workflow YAML parsed; assertions confirmed automatic builds, manual-only
+  release/rollback triggers and the patch/minor/major form choices.
+- `docker compose -f deploy/compose.yaml config --quiet` passed with representative
+  digest references; real NAS Compose validation passed during preparation too.
+- `git diff --check`: passed.
+
+Backend/frontend application code is unchanged. A full Gitea feature/main build
+and dispatched production/recovery evidence remain to be collected after review.
+
+## Required operational acceptance
+
+- [x] Record NAS model/platform, Docker/Compose versions, private endpoint and
+      production directory (no secret values).
+- [x] Verify pinned SSH hostkey, key-only automation and separate registry pull
+      credential. Release-token read access is verified; actual tag-writing
+      acceptance awaits the first release.
+- [ ] Verify release-tag creation/protection with the dedicated token.
+- [ ] Merge workflows through the protected-branch process and identify the
+      successful main build/publication run and SHA.
+- [ ] Demonstrate release form, first release tag and real Synology access;
+      record workflow URL, version, SHA and both deployed digests.
+- [ ] Demonstrate rejected unverified/missing-image release and branch exclusion
+      without modifying production.
+- [ ] Demonstrate duplicate/stale/concurrent release protection, retained tags
+      after failure and exact-SHA retry without another version.
+- [ ] Demonstrate failed candidate recovery while the workflow reports failure,
+      with downloadable diagnostics.
+- [ ] Demonstrate manual rollback without a new version and retained image pairs.
+- [ ] Exercise first-release/recovery failure and interruption/manual recovery
+      using isolated acceptance resources where appropriate.
+- [ ] Confirm fourteen-day artifact retention.
+- [ ] Confirm operator communication of the accepted pre-S16 data-loss policy.
+- [ ] Once S16 applies, verify data preservation and migration compatibility
+      during deployment and rollback (conditional on S16 implementation).
+
+Identify isolated acceptance resources explicitly. Simulated tests are not real
+production evidence.