Skip to content

Joplin Server Runbook

Metadata

Field Value
Service joplin
Criticality Tier 1
Owner Platform owner
Namespace joplin
Clusters local
Last validated 2026-07-31
Related service page ../services/joplin.md

Trigger Conditions

  • https://note.mutana.fr is unavailable.
  • A client reports synchronization or authentication failures.
  • Joplin or PostgreSQL is not Ready.
  • The PostgreSQL PVC or joplin-secrets Secret is unavailable.

1. Health Checks

kubectl -n joplin get deploy,statefulset,pod,svc,pvc,ingressroute
kubectl -n joplin get events --sort-by='.lastTimestamp' | tail -n 20
kubectl -n joplin logs deploy/joplin --tail=200
kubectl -n joplin logs statefulset/joplin-postgres --tail=100
kubectl -n joplin get endpoints joplin joplin-postgres

2. Troubleshooting Workflows

Check prerequisites and workload status without displaying Secret data:

kubectl -n joplin get secret joplin-secrets
kubectl -n joplin describe deploy joplin
kubectl -n joplin describe statefulset joplin-postgres
kubectl -n joplin describe pod -l app.kubernetes.io/part-of=joplin

Common causes are a missing or mismatched database Secret, an unbound local-path PVC, PostgreSQL migration/startup delay, an incorrect APP_BASE_URL, or Traefik routing and TLS failure.

3. Disaster Recovery

  1. Take a logical PostgreSQL dump using credentials from the secure operator environment; do not place credentials or dumps in Git.
  2. Preserve a secure copy of joplin-secrets and optionally snapshot the PVC.
  3. For recovery, restore the Secret first, then the PostgreSQL dump into a compatible PostgreSQL instance.
  4. Reconcile joplin/overlays/local and wait for both workloads to become Ready.
  5. Validate browser login and synchronization from a test client.

Record the first successful restore drill and measured RPO/RTO in this runbook.

4. Scaling and Resource Management

The service intentionally runs one Joplin replica and one PostgreSQL replica. Inspect actual usage before changing the documented resource requests:

kubectl -n joplin top pod
kubectl -n joplin top pod --containers

5. Maintenance Procedures

  • Back up PostgreSQL before every Joplin Server upgrade.
  • Review upstream release notes before changing either pinned image.
  • Change the upstream default administrator credentials immediately after the initial deployment.
  • Rotate database credentials only with a coordinated database and Secret update.

6. Rollback Strategy

Revert the GitOps manifests but preserve the PostgreSQL PVC and Secret. If an upgrade applied incompatible database migrations, restore the pre-upgrade dump instead of starting an older image against the migrated database.

7. Post-Incident Actions

  1. Record the cause, recovery steps, and data-loss window.
  2. Update the measured RPO/RTO after any restore.
  3. Add a changelog fragment for recovery or security-relevant changes.
  4. Update this runbook when the incident reveals a missing diagnostic or step.