Linkwarden

Linkwarden runs in one K3s namespace with three persistent services. Host-level Caddy forwards public HTTPS traffic to the Linkwarden Service; the application uses PostgreSQL for its data and Meilisearch for search.

Each workload uses a Recreate Deployment and a separate local-path PVC. Recreate prevents overlapping pods from mounting these single-writer local volumes during replacement. Kubernetes Secrets hold application and database values; public exposure is configured separately in Caddy.

Fresh installation and ongoing maintenance follow different paths. Bootstrap creates an absent stack from policy-selected compatible versions. Maintenance discovers live images, rejects unsupported transitions, captures recovery evidence, and changes live objects without treating a tracked deployment manifest as competing live state.

Upgrade and recovery

Image selection evaluates same-major and release-maturity policies. PostgreSQL moves within its selected major patch line. The Meilisearch version is derived from the chosen Linkwarden release rather than upgraded independently; unrelated mutable latest tags offer no compatibility evidence.

Stateful Meilisearch version changes use dump/import instead of starting a new binary directly against old data. Linkwarden is quiesced, a dump is created and verified, the previous data directory is preserved, and the target version imports the dump. Index and document counts are compared before normal traffic resumes, and old data remains until the result is accepted.

Before application image mutation, recovery evidence includes live Deployment definitions, image references and immutable digests, and a PostgreSQL dump. Rollback prefers immutable digests. PostgreSQL restoration remains manual because reversing an image must not silently overwrite database data created while the newer version ran.

Classification boundary

The stack exposes the Linkwarden API used by a separate classifier, but Linkwarden itself does not own inference policy. The classifier selects from repository-controlled collections and tags, calls a private inference worker, and mutates only explicitly authorized high-confidence results.

The full workflow, validation contract, stale-state protection, audit design, and feedback loop are covered in the Linkwarden AI Tagger case study.