Skip to content

Joplin Server

Metadata

Field Value
Service joplin
Purpose Private note synchronization for Joplin clients
Criticality Tier 1
Owner Platform owner
Clusters local
Namespace joplin
Exposure internet
Stateful yes
Backup class database
RPO / RTO Pending first backup and restore drill
Last reviewed 2026-07-31

1. Service Overview

Joplin Server provides the synchronization API and account management used by Joplin desktop and mobile clients. Application state, note metadata, and stored resources use the in-cluster PostgreSQL database.

Dependencies

Dependency Type Why it matters
Traefik ingress External HTTPS access for browsers and sync clients
PostgreSQL database Persistent server and note data
local-path storage Persistent database volume on the local cluster

2. Architecture Diagram

[Joplin clients / browser]
  -> [Traefik: note.mutana.fr]
  -> [Joplin Server Deployment]
  -> [PostgreSQL StatefulSet + 50Gi PVC]

3. Deployment Specifications

Item Value
Source path joplin/base and joplin/overlays/local
Deployment model Kustomize plus Fleet bundle
Workloads Joplin Deployment and PostgreSQL StatefulSet
Images joplin/server:3.7.1, postgres:16.8-alpine
Storage local-path, PostgreSQL 50Gi
Probes TCP port 22300; PostgreSQL pg_isready
RBAC No Kubernetes API access; token automount disabled

4. Configuration Guide

APP_BASE_URL is https://note.mutana.fr; Joplin listens on port 22300 and uses PostgreSQL through the joplin-postgres Service.

Secrets management

  • Secret: joplin-secrets in namespace joplin.
  • Required keys: POSTGRES_DATABASE, POSTGRES_USER, POSTGRES_PASSWORD.
  • Source: manually created from an out-of-band env file based on joplin-secrets.env.example.
  • Consumption: secretKeyRef entries in both workloads.
  • Rotation: update the PostgreSQL role and Secret together during a maintenance window, then restart Joplin Server. Do not rotate only one side.
  • Missing Secret impact: neither PostgreSQL nor Joplin Server starts.

5. Access Protocols

Path Endpoint Audience Auth TLS terminates at
Internal joplin.joplin.svc.cluster.local:22300 Cluster diagnostics Joplin auth none
External https://note.mutana.fr Joplin users and clients Joplin Server accounts Traefik

Authelia is intentionally omitted because native clients must access the sync API directly. Change the upstream default administrator credentials immediately after first startup.

6. Operations and Observability

Healthy state requires one Ready Joplin pod, one Ready PostgreSQL pod, a Bound PVC, populated Service endpoints, and a successful HTTPS response at the public hostname.

7. Backup and Recovery Notes

Use a consistent PostgreSQL backup (pg_dump) and preserve the joplin-secrets Secret in the secure out-of-band secret store. A volume snapshot may supplement the database dump but is not a substitute for a tested logical restore. The first backup and restore drill remains required.

8. Release and Change Notes

  • Initial version: Joplin Server 3.7.1 with PostgreSQL 16.8.
  • Rollback: revert the GitOps change while preserving the PVC and Secret; a downgrade after schema migration may require restoring a pre-upgrade dump.