Linkwarden

Linkwarden saves bookmarks and preserved copies of their pages. Behind a single HTTPS address, three workloads have state to protect. Linkwarden has its own file storage, PostgreSQL holds application records, and Meilisearch maintains the search indexes. They share a K3s namespace. Traefik terminates HTTPS and routes requests to the Linkwarden application.

Each workload has its own persistent volume claim on local storage. During a Deployment upgrade, the Recreate strategy stops the old Pods before starting replacements. The application accepts downtime during the change so two revisions do not write to the same volume during rollout. Kubernetes Secrets hold application and database values. Public HTTPS and certificate-hostname acceptance were validated after the ingress cutover.

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.

For a Meilisearch version change, the migration stops Linkwarden so the source stops changing. It creates a dump, checks that there is room to retain the old data, then imports the dump with the target version. Before restarting Linkwarden, it compares the index names and document count for each index with the original, both after import and after a normal search-service restart. Keeping the original directory gives the migration a way back if those checks fail.

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.

Maintenance connects these application-specific checks with the wider recovery and post-change review workflow.

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 applicable high-confidence results.

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