From 718c4bfaeed87a4612d139bf9c6b3b62acfdbeed Mon Sep 17 00:00:00 2001
From: Lucas Winther <lucwin@ece.au.dk>
Date: Mon, 28 Sep 2026 02:53:10 +0200
Subject: [PATCH] docs: specify Gitea image publishing

---
 docs/specs/006-gitea-image-publishing.md | 57 ++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 docs/specs/006-gitea-image-publishing.md

diff --git a/docs/specs/006-gitea-image-publishing.md b/docs/specs/006-gitea-image-publishing.md
new file mode 100644
index 0000000..64d0b27
--- /dev/null
+++ b/docs/specs/006-gitea-image-publishing.md
@@ -0,0 +1,57 @@
+---
+status: draft
+plan: docs/plans/006-gitea-image-publishing.md
+supersedes: none
+---
+
+# 006 — Gitea image publishing
+
+## Why
+
+Operators currently have to clone the repository and build the Docker image themselves. Publish the
+already supported Docker deployment to the project's Gitea container registry so an operator can pull
+a known image and start the service with persistent state and read-only documents.
+
+## Scope
+
+**In:** Gitea Actions checks and image publishing; image naming, tagging and metadata; a deployment
+example using the published image; README instructions for registry access, pulling, startup and
+persistent volumes.
+
+**Out:** automatic deployment to a server; changing the application stack, HTTP API or authentication;
+deleting or rebuilding an index; image signing; multiple CPU architectures in this first release.
+
+## Requirements
+
+- **R1.** Gitea Actions runs tests, lint, type checking and a Docker image build for proposed changes,
+  pushes to `main` and version tags. A failed check prevents the corresponding publishing job from
+  running.
+- **R2.** The image is published to
+  `gitea.lucaswinther.info/lucasw89/recoll-modern` for `linux/amd64` only. A push to `main`
+  publishes the mutable `main` tag. A pushed semantic version tag of the form `vX.Y.Z` publishes
+  that version tag and the mutable `latest` tag. Pull requests never publish.
+- **R3.** The publishing job authenticates with a repository secret holding a Gitea personal access
+  token with package write access. The token is scoped to that job, and instructions explain how to
+  create and set the required username and secret. No credential is committed or printed.
+- **R4.** The published image includes OCI metadata identifying the source repository, description,
+  revision and version or ref, so its provenance is inspectable with Docker.
+- **R5.** A published-image Compose example uses the same port, administrator seed, document mount,
+  state volume, index volume, health check and restart behavior as the local-build deployment. It
+  pulls a selectable image tag and does not require source code or a local build.
+- **R6.** The README gives copyable commands to authenticate when necessary, pull and start a
+  published image, inspect its status, and preserve data during updates. It explains the `main`,
+  `latest` and version-tag meanings, the `linux/amd64` limit, first-boot index readiness, and the
+  difference between documents, service state and index storage.
+- **R7.** The local-build Compose workflow remains available. Publishing changes no application
+  runtime behavior, schema, public API, document data or Recoll index contents.
+
+## Acceptance
+
+1. The workflow file passes a local syntax/structure check, and the complete project checks and
+   Docker build pass in this session.
+2. A published-image Compose configuration validates without invoking a build and references the
+   intended registry image and persistent mounts.
+3. README commands can be followed with only Docker, registry credentials when required, a document
+   directory and administrator seed credentials.
+4. A real publish and pull is verified in Gitea after the branch is merged and the required runner
+   and package-write secret are configured. This cannot be claimed from local checks alone.