docs: explain pulling and running published image

README.md

@@ -6,10 +6,71 @@ full-text search, with support for multiple independent collections.
 Status: spec 001's authenticated search API and Docker deployment have completed acceptance and
 review checks. The web UI and MCP server are later specs.
 
-## Run with Docker
+## Published Docker image
 
-Set `RECOLL_MODERN_DOCUMENTS` to an absolute host directory containing documents and provide a first
-administrator username and password:
+The image is `gitea.lucaswinther.info/lucasw89/recoll-modern` for `linux/amd64`. It currently contains
+the authenticated search API and Recoll; the web UI and MCP server are later specs. `:main` follows
+the main branch. A release tag such as `:v1.2.3` pins a specific release; `:latest` follows the newest
+version tag. Use a version tag when you want a predictable update. The image records its source,
+revision and version in OCI labels (`docker image inspect IMAGE`).
+
+### Run the pulled image with Compose
+
+Save [compose.published.yaml](compose.published.yaml) alongside this guide, or download it from the
+repository after the publishing branch reaches `main`:
+
+```sh
+curl -fL -o compose.published.yaml \
+  https://gitea.lucaswinther.info/lucasw89/recoll-modern/raw/branch/main/compose.published.yaml
+```
+
+If the package is private, log in to the Gitea registry first. Use your Gitea username and a personal
+access token with package **Read** permission as the Docker password:
+
+```sh
+docker login gitea.lucaswinther.info
+```
+
+Set an absolute host directory for documents and seed the first administrator. `:main` is available
+after a successful main-branch publish, even before the first version tag:
+
+```sh
+export RECOLL_MODERN_DOCUMENTS=/srv/documents
+export RECOLL_MODERN_ADMIN_USERNAME=admin
+export RECOLL_MODERN_ADMIN_PASSWORD='use-a-long-unique-password'
+export RECOLL_MODERN_IMAGE=gitea.lucaswinther.info/lucasw89/recoll-modern:main
+docker compose -f compose.published.yaml pull
+docker compose -f compose.published.yaml up -d --no-build
+docker compose -f compose.published.yaml ps
+docker compose -f compose.published.yaml logs -f app
+```
+
+Once a version appears in Gitea Packages, set `RECOLL_MODERN_IMAGE` to its tag, such as
+`gitea.lucaswinther.info/lucasw89/recoll-modern:v1.2.3`, to pin that release. Omit
+`RECOLL_MODERN_IMAGE` to use `:latest` after the first version tag is published. The image is published
+only after the CI checks pass; a tag that has not been published cannot be pulled. To update, set the
+desired tag and run `docker compose -f compose.published.yaml pull` followed
+by `docker compose -f compose.published.yaml up -d --no-build` again. Keep the same Compose project
+directory so its named volumes are reused.
+
+For a trusted local HTTP trial with `docker run`, use the same document and administrator variables:
+
+```sh
+export RECOLL_MODERN_IMAGE=${RECOLL_MODERN_IMAGE:-gitea.lucaswinther.info/lucasw89/recoll-modern:main}
+docker pull "$RECOLL_MODERN_IMAGE"
+docker run -d --name recoll-modern --restart unless-stopped -p 127.0.0.1:8000:8000 \
+  -e RECOLL_MODERN_ADMIN_USERNAME -e RECOLL_MODERN_ADMIN_PASSWORD \
+  -e RECOLL_MODERN_HOST=0.0.0.0 -e RECOLL_MODERN_PORT=8000 \
+  -e RECOLL_MODERN_DEVELOPMENT_MODE=true \
+  --mount "type=bind,src=$RECOLL_MODERN_DOCUMENTS,dst=/documents,readonly" \
+  --mount type=volume,src=recoll-modern-service-state,dst=/var/lib/recoll-modern \
+  --mount type=volume,src=recoll-modern-index,dst=/var/lib/recoll \
+  "$RECOLL_MODERN_IMAGE"
+```
+
+### Build locally
+
+The original `compose.yaml` still builds from this repository:
 
 ```sh
 export RECOLL_MODERN_DOCUMENTS=/srv/documents
@@ -24,6 +85,9 @@ live in the `service-state` volume; the index lives in the separate `recoll-inde
 volumes together and keep a separate copy of the documents. `docker compose down` preserves the volumes;
 never pass `-v` unless you intentionally want to delete the index and service state.
 
+For the direct `docker run` example, the volumes are named `recoll-modern-service-state` and
+`recoll-modern-index`. Back up both together. Replacing a container does not delete these volumes.
+
 On first boot, the API is available but `/health` may return 503 until a membership or reindex job has
 built the first Recoll index. Log in through `POST /auth/login`, create a collection, then add file or
 directory sources through `POST /collections/{id}/memberships`. Mutations return a durable job ID;
@@ -43,5 +107,15 @@ word `zebraplatypus`, set `RECOLL_MODERN_TEST_CORPUS_FILE` to its path relative
 and run `RECOLL_MODERN_REQUIRE_DOCKER=1 uv run pytest tests/integration`. Ordinary host test runs skip
 these checks when Compose is not running. Recoll commands run only inside the container.
 
+## Publishing from Gitea
+
+Enable repository Actions and use a runner with the `ubuntu-latest` label, Python 3, `uv` setup support,
+and a working Docker CLI/daemon. In the repository's Actions secrets, set `REGISTRY_USERNAME` to the
+Gitea account that owns the publishing token and `REGISTRY_TOKEN` to a personal access token with
+package **Read & Write** permission. Gitea currently [requires a PAT for Actions package
+publishing](https://docs.gitea.com/usage/actions/comparison/); the built-in job token does not publish
+OCI packages. The workflow checks pull requests without registry credentials and publishes only after
+checks pass on `main` or a full `vX.Y.Z` tag. No server deployment is performed by CI.
+
 Working here (human or agent): read [`AGENTS.md`](AGENTS.md). It is the single source of truth for
 commands, workflow, and boundaries. Deeper context lives in [`docs/`](docs/).