Self-Hosting Note Taking: Joplin Server on Debian Linux (End-to-End Encrypted Markdown & PostgreSQL)

Executive Summary: Joplin is the leading open-source, offline-first Markdown knowledge base for engineers and researchers across Linux, Android, iOS, Windows, and macOS. While Joplin can sync over generic WebDAV or Nextcloud, WebDAV suffers from severe latency when syncing thousands of small note fragments on mobile devices. Self-hosting the dedicated Joplin Server container backed by PostgreSQL accelerates delta synchronization by 10×, enables collaborative notebook sharing, and allows 1-click public note publishing while preserving 100% client-side End-to-End Encryption (E2EE).

• Zero-Knowledge Client E2EE

  ---

  Notes, tags, and attachments are encrypted locally on your device using your Master Password (AES-256) before ever leaving your laptop or phone.

• 10× Faster Delta Sync

  ---

  Replaces chatty WebDAV directory listings (PROPFIND) with a batched delta REST API backed by PostgreSQL 16/17.

• Engineering Markdown & Mermaid

  ---

  Write portable CommonMark Markdown with built-in Mermaid diagrams, KaTeX math, syntax-highlighted code blocks, and Web Clipper support.

• Notebook Sharing & Publishing

  ---

  Share specific project notebooks across team accounts or publish single read-only runbooks via a unique web URL.

---

1. Joplin E2EE Synchronization Architecture

Even if an attacker gained root access to your cloud VPS, an E2EE-enabled Joplin Server database contains only opaque ciphertext blobs—all decryption and full-text search indexing happen strictly inside the local SQLite database on your trusted client devices:

%%{init: {'flowchart': {'wrappingWidth': 600}}}%%
flowchart TB
    DESK["💻 Linux Desktop Client<br/>Plaintext Markdown -> AES-256<br/>(Local Master Key)"]
    SRV["🛡️ Joplin Server API<br/>127.0.0.1:22300<br/>(Stores Ciphertext Only!)"]
    PG["🗄️ PostgreSQL 17<br/>Indexed Delta Sync Store<br/>(/var/lib/postgresql/data)"]
    MOB["📱 iOS / Android Client<br/>Downloads Ciphertext -><br/>Decrypts Locally"]

    DESK ==>|"HTTPS Delta Push"| SRV
    SRV <--> PG
    SRV ==>|"HTTPS Delta Pull"| MOB

---

2. Production compose.yaml (Joplin Server + PostgreSQL 17)

Deploy joplin/server bound to 127.0.0.1:22300 alongside a dedicated PostgreSQL 17 container:

# File: /srv/containers/joplin/compose.yaml
services:
  joplin-server:
    image: docker.io/joplin/server:latest
    container_name: joplin-server
    depends_on:
      joplin-db:
        condition: service_healthy
    restart: unless-stopped
    ports:
      - "127.0.0.1:22300:22300/tcp"
    environment:
      - APP_PORT=22300
      - APP_BASE_URL=https://notes.nejat-hakan.de
      - DB_CLIENT=pg
      - POSTGRES_HOST=joplin-db
      - POSTGRES_PORT=5432
      - POSTGRES_DATABASE=joplin
      - POSTGRES_USER=joplin
      - POSTGRES_PASSWORD=${JOPLIN_DB_PASSWORD}
      - STORAGE_DRIVER=Type=Database

  joplin-db:
    image: docker.io/library/postgres:17-bookworm
    container_name: joplin-db
    restart: unless-stopped
    environment:
      - POSTGRES_DB=joplin
      - POSTGRES_USER=joplin
      - POSTGRES_PASSWORD=${JOPLIN_DB_PASSWORD}
    volumes:
      - /srv/containers/joplin/postgres:/var/lib/postgresql/data:rw
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U joplin -d joplin"]
      interval: 10s
      timeout: 5s
      retries: 5

---

3. Initial Admin Hardening & Client E2EE Setup

Change the Default admin@localhost Credentials Immediately!

On first boot, Joplin Server seeds a bootstrap administrator account with username admin@localhost and password admin. Before exposing https://notes.nejat-hakan.de through your reverse proxy, log in immediately, change the admin email and password, and create a separate non-admin user account for daily note synchronization.

Configuring Joplin Desktop & Mobile Clients

1. Open Joplin → Tools → Options → Synchronization.
2. Synchronization target: Select Joplin Server.
3. Joplin Server URL: https://notes.nejat-hakan.de
4. Enter your non-admin user email and password, then click Check synchronization configuration.
5. Navigate to Options → Encryption → Click Enable Encryption and set a high-entropy Master Password (store this Master Password in your Vaultwarden password manager!).

---

Where to Go Next

Complete your sovereign productivity stack with Vikunja task management and Vaultwarden password security:

• Vikunja Task & Project Management

  ---

  Pair Joplin documentation with Kanban boards, Gantt charts, and CalDAV task lists in Vikunja.

  Vikunja Guide

• Vaultwarden Password Manager

  ---

  Store your Joplin E2EE Master Password and SSH keys securely in a self-hosted Bitwarden-compatible vault.

  Vaultwarden Guide

• Caddy Reverse Proxy

  ---

  Terminate HTTPS/TLS 1.3 in front of Joplin Server (127.0.0.1:22300) automatically.

  Caddy Guide