Joplin — Administrator & Developer Guide

Joplin is a free, open-source note-taking and to-do application with end-to-end encryption, synchronization across devices, and an extensible plugin system. This guide covers the full architecture, configuration, deployment, security posture, and developer internals of the Joplin ecosystem — a monorepo spanning 20+ packages that produces Desktop (Electron), Mobile (React Native), CLI (Node.js), Server (Node.js + PostgreSQL), and Web Clipper (browser extension) applications.

For everyday usage, installation walkthroughs, and feature guides, see the User Guide.

1. Architecture Overview

1.1 High-Level System Topology

┌─────────────────────────────────────────────────────────────────────────┐
│                         Joplin Ecosystem                                │
│                                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌────────────┐  │
│  │  app-desktop  │  │  app-mobile   │  │   app-cli    │  │ app-clipper│  │
│  │  (Electron)   │  │(React Native) │  │  (Node.js)   │  │ (Browser)  │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └─────┬──────┘  │
│         │                 │                 │                 │          │
│         └────────┬────────┴────────┬────────┘                │          │
│                  │                 │                          │          │
│           ┌──────▼───────┐  ┌─────▼──────┐           ┌──────▼───────┐  │
│           │     lib      │  │  renderer  │           │   REST API   │  │
│           │(Models/Sync/ │  │ (Markdown) │           │  (localhost)  │  │
│           │ Services)    │  │            │           │              │  │
│           └──────┬───────┘  └────────────┘           └──────────────┘  │
│                  │                                                      │
│         ┌────────▼────────────────────────────────────────────────┐     │
│         │              Sync Layer (SyncTargetRegistry)            │     │
│         │                                                        │     │
│         │  ┌─────────┐ ┌──────────┐ ┌────────┐ ┌──────────────┐ │     │
│         │  │Joplin   │ │Nextcloud/│ │OneDrive│ │  S3/Dropbox  │ │     │
│         │  │Cloud/   │ │WebDAV    │ │        │ │  /Filesystem │ │     │
│         │  │Server   │ │          │ │        │ │              │ │     │
│         │  └────┬────┘ └──────────┘ └────────┘ └──────────────┘ │     │
│         └───────┼────────────────────────────────────────────────┘     │
│                 │                                                      │
│         ┌───────▼────────┐                                             │
│         │  Joplin Server │                                             │
│         │  (Koa + PG)    │                                             │
│         └───────┬────────┘                                             │
│                 │                                                      │
│         ┌───────▼────────┐                                             │
│         │  PostgreSQL    │                                             │
│         └────────────────┘                                             │
└─────────────────────────────────────────────────────────────────────────┘

Note

Joplin's architecture is a monorepo with clear package boundaries. The lib package is the gravitational center — every client application depends on it for models, synchronization logic, encryption, and service management. The server is an independent deployment that shares data format conventions but runs its own Koa-based stack with PostgreSQL.

1.2 Monorepo Package Inventory

The repository uses Yarn 4.9.2 workspaces to manage 25+ packages under the packages/ directory:

1.3 Data Flow: Note Lifecycle

User creates/edits note
        │
        ▼
┌─────────────────┐
│  Editor Layer   │  CodeMirror 6 (Markdown) / TinyMCE (WYSIWYG)
│  (app-desktop/  │  ProseMirror (mobile WYSIWYG)
│   app-mobile)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   BaseModel     │  Note model validates, assigns metadata
│   (lib)         │  (id, parent_id, timestamps, markup_language)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   SQLite DB     │  Local persistence (WAL mode, FK enforcement)
│   (client)      │  Schema migrations managed per version
└────────┬────────┘
         │
         ▼  (on sync trigger)
┌─────────────────┐
│   Synchronizer  │  Delta-based sync, lock conflict resolution
│   (lib)         │  Attachment download mode: always/manual/auto
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Sync Target   │  Joplin Server / Cloud / Nextcloud / WebDAV /
│   (lib)         │  OneDrive / Dropbox / S3 / Filesystem
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Remote Storage │  Server-side PostgreSQL or file-based target
└─────────────────┘

1.4 Sync Target Registry

All synchronization backends are registered through SyncTargetRegistry with numeric identifiers:

Max concurrent sync connections: configurable 1–20, default 5.

1.5 Client-Side Application Architecture

Each client application follows a common pattern rooted in BaseApplication:

BaseApplication
├── Application (Desktop) ─── extends ──→ Bridge (Electron IPC)
├── Application (CLI) ──────── extends ──→ AppGui (terminal-kit)
└── AppComponent (Mobile) ── React Native root component

Key shared services instantiated by all clients:

• Setting — centralized configuration (JSON file or SQLite-backed)
• SyncTargetRegistry — sync backend selection
• DecryptionWorker — background E2EE decryption
• SearchEngine — full-text search (FTS4/FTS5 on SQLite)
• AlarmService — to-do reminder scheduling
• PluginService — plugin lifecycle management (desktop only)
• ResourceEditWatcher — external editor integration
• ExternalEditWatcher — file system monitoring for note editing
• EventManager — pub/sub event bus
• Logger — structured logging with configurable levels

2. System Requirements

2.1 Joplin Server

2.2 Desktop Application (Development)

2.3 Mobile Application (Development)

2.4 CLI Application

2.5 OneNote Converter

2.6 Build System Requirements

The full monorepo build requires:

# Install dependencies (Yarn 4.9.2 workspaces)
yarn install

# Build all packages (order-aware via workspace dependencies)
yarn build

# Individual package builds use Gulp tasks internally

Key build tooling:

• Yarn 4.9.2 — workspace management, dependency resolution
• Gulp — task orchestration within packages
• Electron Builder — desktop packaging (Windows/macOS/Linux installers)
• React Native CLI — mobile builds (iOS/Android)
• Rust/wasm-pack — OneNote converter WASM compilation
• Playwright — integration testing framework

3. Configuration Reference

3.1 Settings Architecture

Joplin uses a centralized Setting class that manages 100+ configuration options. Settings are persisted via two storage backends:

Settings are organized into sections:

Settings have per-app-type visibility flags controlling which settings appear in Desktop, Mobile, or CLI.

Important

Secure settings (sync passwords, encryption passphrases) are stored via the operating system's native keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service). These values are never written to the JSON settings file in plaintext. If the keychain is unavailable, Joplin falls back to database storage with a warning.

3.2 Server Environment Variables

The Joplin Server accepts the following environment variables:

3.3 Database Configuration

The server reads database configuration from a file specified by db-config-filename. The PostgreSQL connection parameters include:

• Host and port
• Database name
• Username and password
• SSL configuration
• Connection pool settings
• Connection timeout (triggers "Timeout trying to connect to database" on failure)

3.4 Client Settings — Complete Reference

Below is the complete catalog of built-in settings, organized by section. Each setting includes its type, default value (where deterministic), and the app types where it is visible.

3.4.1 Sync Settings

3.4.2 Appearance Settings

3.4.3 Note Settings

3.4.4 Editor Settings

3.4.5 Encryption Settings

3.4.6 Plugin Settings

3.4.7 Advanced Settings

3.5 Profile Configuration

Joplin supports multiple profiles via ProfileConfig:

• Each profile has its own settings file, database, and sync target
• Profile switching is available on desktop
• Profile data is isolated — notes, notebooks, and resources are per-profile
• The default profile is profile 0

4. Deployment & Scaling

4.1 Joplin Server Deployment

4.1.1 Docker Deployment (Recommended)

The standard deployment uses Docker with PostgreSQL:

# docker-compose.yml
version: '3'
services:
  db:
    image: postgres:16
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=<strong_password>
      - POSTGRES_USER=joplin
      - POSTGRES_DB=joplin
    restart: unless-stopped

  app:
    image: joplin/server:latest
    depends_on:
      - db
    ports:
      - "22300:22300"
    environment:
      - APP_PORT=22300
      - APP_BASE_URL=https://joplin.yourdomain.com
      - DB_CLIENT=pg
      - POSTGRES_PASSWORD=<strong_password>
      - POSTGRES_DATABASE=joplin
      - POSTGRES_USER=joplin
      - POSTGRES_PORT=5432
      - POSTGRES_HOST=db
    restart: unless-stopped

4.1.2 Reverse Proxy Configuration

For production, place the server behind a reverse proxy (Nginx, Traefik, Caddy):

# Nginx example
server {
    listen 443 ssl;
    server_name joplin.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    client_max_body_size 200M;  # For large attachments

    location / {
        proxy_pass http://127.0.0.1:22300;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

4.1.3 Bare Metal Deployment

# Clone and build
git clone https://github.com/laurent22/joplin.git
cd joplin
yarn install
cd packages/server
yarn build

# Configure database
export DB_CLIENT=pg
export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432
export POSTGRES_DATABASE=joplin
export POSTGRES_USER=joplin
export POSTGRES_PASSWORD=<password>
export APP_BASE_URL=https://joplin.yourdomain.com

# Run migrations and start
yarn start

4.2 Database Migrations

The server manages schema migrations automatically on startup. If migrations are pending, the server logs:

One or more migrations need to be applied

Migrations run in sequence. The server will not start serving requests until all migrations complete. For large databases, plan for downtime during major version upgrades.

4.3 Scaling Considerations

4.3.1 Vertical Scaling

4.3.2 Storage Planning

Storage grows with:

• Note content (typically small, < 1 KB per note)
• Attachments/resources (images, PDFs — can be large)
• Note revisions (90-day retention by default)
• Server-side item versions for delta sync

Formula: base_storage = num_users * avg_attachments_per_user * avg_attachment_size * 1.2 (overhead)

4.3.3 Connection Pooling

PostgreSQL connections are managed via a connection pool in the server. The TransactionHandler manages transaction lifecycle, ensuring proper isolation and cleanup. Configure PostgreSQL's max_connections based on expected concurrency — each active sync session can consume 1–3 connections.

4.4 Desktop Distribution

Electron Builder produces platform-specific packages:

4.5 Mobile Distribution

5. Operations

5.1 Server Administration

5.1.1 User Management

The server exposes user management through its API and admin interface:

POST   /api/users          Create user
GET    /api/users           List users
GET    /api/users/:id       Get user details
PATCH  /api/users/:id       Update user

Note

The first user created on a fresh Joplin Server instance is automatically an admin. Subsequent users are standard users by default. Admin privileges can be granted via the PATCH endpoint or the web admin interface.

User accounts can be disabled, which triggers the error "This account is disabled" on any subsequent authentication attempt.

5.1.2 Session Management

Sessions are managed through the /api/sessions endpoint:

POST   /api/sessions        Create session (login)

Sessions have configurable expiration. Expired sessions trigger: "Your session has expired."

5.1.3 Health Monitoring

GET    /api/ping            Basic health check (no auth required)
GET    /api/debug           Debug information (admin only)

Tip

Use /api/ping for load balancer health checks and container orchestrator liveness probes. It returns a simple response without touching the database. Use /api/debug for deeper diagnostics, but protect it behind authentication as it may expose internal state.

5.1.4 Batch Operations

The server supports batch operations to reduce round-trips during sync:

POST   /api/batch           Execute multiple operations atomically
POST   /api/batch_items     Batch item operations

These endpoints are used internally by the sync engine. Direct use requires understanding the item serialization format.

5.2 Backup Strategies

5.2.1 Server Backup

# PostgreSQL dump
pg_dump -U joplin -d joplin -F c -f joplin_backup_$(date +%Y%m%d).dump

# Restore
pg_restore -U joplin -d joplin -c joplin_backup_20260507.dump

Back up both the database and the attachment storage directory. The database contains item metadata and content; attachments are stored as binary blobs or on the filesystem depending on configuration.

5.2.2 Client Backup

Client data lives in the local SQLite database and a resources directory:

Back up: database.sqlite, resources/, settings.json, and keymap-desktop.json.

5.3 Log Management

Joplin uses a structured Logger class with configurable levels:

Desktop logs: accessible via Help -> Open Log Directory.

Server logs: standard output (capture via Docker logging driver or systemd journal).

5.4 Monitoring Checklist

Note

The PerformanceTimer class in the server provides internal timing metrics for request processing. Enable debug logging to capture per-route latency data for performance analysis.

6. Performance

6.1 Client-Side Performance

6.1.1 SQLite Optimization

Joplin clients use SQLite with the following performance-critical settings:

• WAL mode — Write-Ahead Logging enables concurrent reads during writes, essential for smooth UI during sync
• Foreign key enforcement — enabled at connection time (PRAGMA foreign_keys = ON)
• Full-text search — FTS4/FTS5 extensions for note search, configurable via db.ftsEnabled

6.1.2 Search Engine

The SearchEngine service maintains a full-text index:

• Index rebuild runs on first launch or after profile import
• Incremental indexing on note save
• Supports quoted phrases, AND/OR operators, tag filters
• FTS5 preferred where available (better ranking, prefix queries)

6.1.3 Resource Management

Attachments (resources) are the primary driver of storage and bandwidth:

6.2 Server-Side Performance

6.2.1 Delta Sync

The server implements delta-based synchronization via the items API:

GET    /api/items/:id/delta     Retrieve changes since cursor

Delta sync minimizes data transfer by sending only changed items since the client's last sync cursor. A client with 10,000 notes only transfers the handful that changed since the last sync.

6.2.2 Rate Limiting

The server implements rate limiting middleware to prevent abuse:

• Returns ErrorTooManyRequests (HTTP 429) when limits are exceeded
• Per-user or per-IP rate limiting
• Configurable thresholds

6.2.3 Caching

The server uses a Cache class for frequently accessed data:

• In-memory cache with TTL-based expiration
• Reduces database queries for hot paths (user sessions, item metadata)
• Cache invalidation on write operations

6.2.4 Payload Limits

Large attachments trigger ErrorPayloadTooLarge (HTTP 413). Configure:

• Reverse proxy: client_max_body_size (Nginx) or equivalent
• Server-side: payload size limits in server configuration
• Client-side: resource upload chunking for large files

6.3 Performance Tuning Checklist

7. Security

7.1 End-to-End Encryption (E2EE)

Joplin implements E2EE with a master key architecture:

┌─────────────────────────────────────────────────────┐
│                  E2EE Architecture                   │
│                                                      │
│  Master Password ──→ Master Key (encrypted)          │
│                       │                              │
│                       ▼                              │
│              Decrypt Master Key                      │
│                       │                              │
│                       ▼                              │
│              Per-Item Encryption                     │
│              (AES-256-CBC)                           │
│                       │                              │
│              ┌────────┴────────┐                     │
│              ▼                 ▼                     │
│         Note Content     Resource Data               │
│         (encrypted)      (encrypted)                 │
│                                                      │
│  Public-Private Keys (PPK):                          │
│  ├── WebCrypto RSA key pairs                         │
│  ├── Used for sharing encrypted notebooks            │
│  └── Per-user key pair generation                    │
│                                                      │
│  DecryptionWorker:                                   │
│  ├── Background service                              │
│  ├── Processes encrypted items in batches            │
│  └── Checks per-item encryption status               │
└─────────────────────────────────────────────────────┘

Warning

Losing the master password means permanent data loss for encrypted notes. There is no recovery mechanism by design — the server never has access to decryption keys. Ensure users understand this before enabling E2EE. Store the master password in a secure password manager.

Key implementation details:

• Master key rotation: supported but requires re-encryption of all items (triggered via encryption.shouldReencrypt)
• Per-item check: each item carries its own encryption flag, enabling gradual encryption/decryption
• PPK (Public-Private Keys): WebCrypto-based RSA key pairs enable notebook sharing between users with E2EE active
• DecryptionWorker: runs as a background service, processing encrypted items without blocking the UI

7.2 Server Authentication

7.2.1 Session-Based Auth

Standard authentication flow:

1. Client sends credentials to POST /api/sessions
2. Server validates and returns session token
3. Client includes token in subsequent requests
4. Invalid/expired tokens yield "Invalid or missing session" or "Your session has expired"

7.2.2 SAML Authentication

Enterprise SSO via SAML (sync target ID 11):

GET    /api/saml          SAML metadata / initiate flow
POST   /api/saml          SAML assertion consumer
GET    /api/login_with_code/:id   Complete SAML login

SAML must be explicitly enabled in server configuration. When disabled, requests to SAML endpoints return: "SAML support is disabled."

7.2.3 Application Auth

GET/POST  /api/application_auth    Application-level authentication

Used for OAuth-style application authorization flows.

7.3 CSRF Protection

The server implements CSRF protection middleware:

• CSRF tokens are required for state-changing requests
• Missing tokens trigger: "CSRF token is missing"
• Invalid tokens trigger: "Invalid CSRF token"
• Tokens are validated per-request

Caution

API integrations that bypass the web interface must handle CSRF tokens correctly. Obtain a token from the login response and include it in all subsequent POST/PATCH/DELETE requests. Failure to do so results in 403 Forbidden responses.

7.4 Client REST API Security

The local REST API (port 41184 by default) is secured via token authentication:

GET    /api/ping           No auth required
GET    /api/notes           Requires api.token
POST   /api/notes           Requires api.token
GET    /api/folders          Requires api.token
...

The REST API listens on localhost only. The api.token setting controls access. The Web Clipper and plugins use this API.

Error classes for the client REST API:

7.5 Server Error Hierarchy

The server uses a comprehensive ApiError hierarchy for consistent error handling:

7.6 Network Security

7.7 Data Protection

7.8 Plugin Security

Warning

Plugins execute within a sandbox but have access to note data through the JoplinData API. Only install plugins from trusted sources. The plugin system validates manifest fields (ID: 16-256 characters, version: semver pattern) but cannot guarantee code safety. Review plugin permissions before installation.

Plugin security model:

• Sandbox execution: plugins run in isolated contexts via executeSandboxCall
• API surface control: plugins access data through JoplinData (CRUD) and JoplinImaging (image manipulation)
• Platform compatibility: plugins declare supported platforms; incompatible plugins are rejected
• Content scripts: loaded with plugin/default export pattern, restricted to declared capabilities

8. Developer Internals

8.1 Core Data Model

The data model is rooted in BaseModel with type-specific subclasses:

BaseModel
├── BaseItem (sync-capable items)
│   ├── Note          (type: 1)
│   ├── Folder        (type: 2) [Notebook]
│   ├── Resource      (type: 4) [Attachment]
│   ├── Tag           (type: 5)
│   ├── NoteTag       (type: 6) [Join table]
│   ├── MasterKey     (type: 9)
│   └── Revision      (type: 13)
└── Setting           (singleton, not synced as item)

Key model properties shared across types:

8.2 Server Model Layer

The server uses a Models factory class to instantiate model objects:

// Models factory provides typed access to all model classes
const models = new Models(db, config);
const user = await models.user().load(userId);
const items = await models.item().loadByIds(itemIds);

Model classes follow the BaseModel pattern with:

• CRUD operations via database abstraction
• Validation hooks
• Event emission on state changes
• Transaction support via TransactionHandler

8.3 Server Route Architecture

Routes follow a RESTful pattern under /api/:

8.4 Complete Server API Reference

Items API

GET    /api/items/:id              Retrieve item content
PUT    /api/items/:id              Update item content
GET    /api/items/:id/delta        Get changes since cursor
GET    /api/items/:id/children     List child items

The items API is the backbone of synchronization. Each item is identified by a unique ID and versioned. The delta endpoint enables efficient incremental sync by returning only items modified since the provided cursor.

Sessions API

POST   /api/sessions              Create session (authenticate)

Request body: { "email": "...", "password": "..." }

Returns a session token for subsequent authenticated requests.

Users API

POST   /api/users                 Create user
GET    /api/users                 List users
GET    /api/users/:id             Get user details
GET    /api/users/:id/public_key  Get user's public key (E2EE sharing)
PATCH  /api/users/:id             Update user

Shares API

POST   /api/shares                Create share (notebook sharing)
GET    /api/shares                List shares
GET    /api/shares/:id            Get share details
POST   /api/shares/:id/users      Add user to share
GET    /api/shares/:id/users       List share members

Share Users API

GET    /api/share_users           List share user associations
PATCH  /api/share_users/:id       Update share user (accept/reject)

Locks API

POST   /api/locks                 Acquire sync lock
GET    /api/locks                 List active locks

Sync locks prevent concurrent modifications during synchronization. Lock types support exclusive and shared access patterns.

Batch API

POST   /api/batch                 Execute batch operations
POST   /api/batch_items           Execute batch item operations

Used by sync clients to bundle multiple operations into a single HTTP request, reducing latency for operations that would otherwise require sequential round-trips.

Events API

GET    /api/events                List events
POST   /api/events                Create event

The events system enables server-side event tracking and notification.

Transcription API

POST   /api/transcribe            Submit audio for transcription
GET    /api/transcribe/:id        Get transcription result

Used by the voice typing feature. Processes audio files through the transcription service.

SAML API

GET    /api/saml                  SAML metadata / initiate SSO
POST   /api/saml                  SAML assertion consumer service
GET    /api/login_with_code/:id   Complete SAML login flow

Utility Endpoints

GET/POST  /api/application_auth   Application authentication
GET       /api/ping               Health check (returns "JoplinServer")
GET       /api/debug              Debug information (admin only)

8.5 Editor Stack

Joplin's editor is a sophisticated multi-layer system:

┌─────────────────────────────────────────────────────┐
│                   Editor Stack                       │
│                                                      │
│  Desktop:                                            │
│  ┌──────────────┐  ┌──────────┐  ┌──────────────┐  │
│  │ CodeMirror 6 │  │ TinyMCE  │  │ Plain Editor │  │
│  │ (Markdown)   │  │ (WYSIWYG)│  │ (Fallback)   │  │
│  └──────────────┘  └──────────┘  └──────────────┘  │
│                                                      │
│  Mobile:                                             │
│  ┌──────────────┐  ┌────────────┐                   │
│  │ CodeMirror   │  │ ProseMirror│                   │
│  │ (Markdown)   │  │ (WYSIWYG)  │                   │
│  └──────────────┘  └────────────┘                   │
│                                                      │
│  CLI:                                                │
│  ┌──────────────────────────────┐                   │
│  │ terminal-kit Text Widget     │                   │
│  └──────────────────────────────┘                   │
│                                                      │
│  Custom Components:                                  │
│  ├── JoplinLists (TinyMCE plugin)                   │
│  ├── FloatingButtonBar (mobile toolbar)             │
│  ├── ButtonRow (action buttons)                     │
│  └── ElementObserver (DOM monitoring)               │
└─────────────────────────────────────────────────────┘

8.6 Plugin System Deep Dive

8.6.1 Plugin Lifecycle

Discovery -> Validation -> Loading -> Sandbox Init -> Execution -> Teardown

1. Discovery: plugins found in plugin directory or via plugins.devPluginPaths
2. Validation: manifest checked (ID: 16-256 chars, semver version, required fields)
3. Loading: plugin bundle loaded into sandboxed context
4. Sandbox Init: executeSandboxCall creates isolated execution environment
5. Execution: plugin registers handlers, commands, views
6. Teardown: cleanup on disable/uninstall

8.6.2 Plugin API Surface

// JoplinData — CRUD access to Joplin entities
joplin.data.get(['notes'], { fields: ['id', 'title'] });
joplin.data.post(['notes'], null, { title: 'New Note', body: '...' });
joplin.data.put(['notes', noteId], null, { title: 'Updated' });
joplin.data.delete(['notes', noteId]);

// JoplinImaging — image manipulation
joplin.imaging.createFromPath(imagePath);
joplin.imaging.resize(handle, { width: 800 });

Supported data types: notes, folders, tags, resources, search

8.6.3 Content Scripts

Content scripts extend the renderer with custom markdown tokens and rendering logic:

// Content script pattern
module.exports = function(context) {
    return {
        plugin: function(markdownIt, options) {
            // Register custom markdown-it plugin
        },
        assets: function() {
            return [{ name: 'style.css' }];
        }
    };
};

8.6.4 Default Plugins

The default-plugins package manages built-in plugins that ship with the desktop application. These are built through a pipeline that:

1. Resolves plugin source from the plugin repository
2. Builds each plugin
3. Packages them into the desktop distribution
4. Handles updates through the plugin update mechanism

8.6.5 Plugin Generator

The generator-joplin package provides a Yeoman generator for scaffolding new plugins:

npx yo joplin
# Prompts for plugin name, description, etc.
# Generates plugin skeleton with manifest, entry point, and build config

8.7 Markdown Renderer

The renderer package converts Markdown to HTML with extensive plugin support:

8.8 Import/Export Architecture

8.8.1 HTML Processing

The turndown package (forked) converts HTML to Markdown, with turndown-plugin-gfm adding GitHub Flavored Markdown support (tables, strikethrough, task lists). The fork-htmlparser2 and fork-sax packages provide the underlying HTML/XML parsing.

Utility classes:

• HtmlUtils — HTML sanitization and transformation
• MarkupLanguageUtils — markup type detection and conversion
• WelcomeUtils — initial welcome note generation

8.8.2 OneNote Import

The onenote-converter package is a Rust application compiled to WASM:

• Parses OneNote .one files
• Converts OneNote page structure to Joplin notes
• Handles embedded images and attachments
• Known issue #15132: import can hang during postprocessing for complex notebooks

8.9 OCR System

Joplin implements Optical Character Recognition for searchable attachments:

8.10 Transcription Service

The transcribe package provides server-side audio transcription:

• Accepts audio file uploads via POST /api/transcribe
• Returns transcription results via GET /api/transcribe/:id
• Used by the voice typing feature on mobile (backed by whisper-voice-typing C++/Whisper on Android)

8.11 Key Service Classes

8.12 CLI Command Reference

The CLI application (app-cli) includes 42 command classes covering full Joplin functionality:

8.13 Build System Details

8.13.1 Workspace Structure

// Root package.json (simplified)
{
  "workspaces": ["packages/*"],
  "packageManager": "yarn@4.9.2"
}

8.13.2 Build Order

Package dependencies enforce build order:

utils -> lib -> renderer -> editor -> app-desktop
                                   -> app-mobile
                                   -> app-cli
                           -> server
fork-htmlparser2 -> turndown -> lib
onenote-converter (standalone Rust/WASM build)

8.13.3 Testing

# Run all tests
yarn test

# Run tests for specific package
cd packages/lib && yarn test

# Playwright (desktop integration)
cd packages/app-desktop && yarn test-integration

9. Integration Points

9.1 Sync Target Integration

9.1.1 WebDAV (Generic)

Sync Target ID: 6
Protocol: WebDAV (RFC 4918)
Authentication: Basic or Digest
Path: Full URL to WebDAV endpoint

WebDavApi handles all WebDAV protocol operations including PROPFIND, MKCOL, PUT, GET, DELETE with retry logic and error mapping.

9.1.2 Nextcloud

Sync Target ID: 5
Protocol: WebDAV (Nextcloud-specific paths)
Authentication: Basic auth or app passwords
Path: https://nextcloud.example.com/remote.php/webdav/Joplin

Nextcloud support builds on the WebDAV target with Nextcloud-specific endpoint detection.

9.1.3 OneDrive

Sync Target ID: 3 (personal) / 4 (business)
Protocol: Microsoft Graph API
Authentication: OAuth 2.0

Uses Microsoft's authentication flow. Business accounts (ID 4) use different Graph API endpoints.

9.1.4 Dropbox

Sync Target ID: 7
Protocol: Dropbox API v2
Authentication: OAuth 2.0

DropboxApi wraps the Dropbox HTTP API with session management and file operations.

9.1.5 Amazon S3

Sync Target ID: 8
Protocol: S3 (AWS SDK)
Authentication: Access Key + Secret
Endpoint: Configurable (supports MinIO, Wasabi, etc.)

SyncTargetAmazonS3 supports any S3-compatible storage provider.

9.1.6 Filesystem

Sync Target ID: 2
Protocol: Local filesystem
Path: Absolute path to sync directory

No network required. Useful for USB-drive sync or local backup.

9.1.7 Joplin Server / Joplin Cloud

Sync Target ID: 9 (Server) / 10 (Cloud) / 11 (Server + SAML)
Protocol: Joplin REST API
Authentication: Session token or SAML

The most feature-complete sync target, supporting notebook sharing, E2EE key exchange, and delta sync.

9.2 Web Clipper Integration

The Web Clipper browser extension communicates with the desktop/CLI application via the local REST API:

Desktop/CLI <--REST API (localhost:41184)--> Web Clipper Extension

Clipping modes:

• Simplified page (article extraction)
• Complete page (full HTML)
• Screenshot (visible area)
• URL only (bookmark)
• Selection (highlighted text)

9.3 External Editor Integration

Joplin supports external text editors via ExternalEditWatcher:

1. User triggers "Edit in external editor"
2. Joplin writes note content to a temporary file
3. External editor opens the file
4. ExternalEditWatcher monitors for changes (filesystem events)
5. Changes are synced back to the note in real-time

Configure via editor setting (e.g., code, vim, subl).

9.4 REST API Integration (Client-Side)

Third-party applications and scripts interact with Joplin via the local REST API:

# List all notes
curl http://localhost:41184/notes?token=YOUR_TOKEN

# Create a note
curl -X POST http://localhost:41184/notes?token=YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"title": "API Note", "body": "Created via REST API"}'

# Search notes
curl "http://localhost:41184/search?query=keyword&token=YOUR_TOKEN"

# Get all tags
curl http://localhost:41184/tags?token=YOUR_TOKEN

# Get all folders (notebooks)
curl http://localhost:41184/folders?token=YOUR_TOKEN

# Get a specific resource (attachment)
curl http://localhost:41184/resources/RESOURCE_ID?token=YOUR_TOKEN

# Ping (no auth required)
curl http://localhost:41184/ping

All data endpoints require the token query parameter matching the api.token setting.

9.5 PDF Viewer

The pdf-viewer package provides embedded PDF viewing in the desktop application:

• React-based PDF rendering
• Integrated with the resource system
• Supports OCR text overlay for searchable PDFs

9.6 HTML Pack

The htmlpack package creates self-contained HTML files:

• Bundles CSS, images, and scripts inline
• Used for export and note sharing
• Produces single-file HTML that renders identically to the original

10. Troubleshooting

10.1 Server Issues

Problem: "Timeout trying to connect to database"

Cause: PostgreSQL is unreachable or not accepting connections.

Resolution:

1. Verify PostgreSQL is running: pg_isready -h <host> -p <port>
2. Check connection parameters in database config file
3. Verify firewall rules allow connections on the PostgreSQL port
4. Check PostgreSQL pg_hba.conf for authentication rules
5. Increase connection timeout if the database is under heavy load

Problem: "Postgres version not supported"

Cause: The installed PostgreSQL version is below the minimum enforced by Joplin Server.

Resolution: Upgrade PostgreSQL to the required minimum version. Check server startup logs for the exact minimum version required.

Problem: "One or more migrations need to be applied"

Cause: Database schema is behind the server version.

Resolution: This is informational — migrations run automatically on startup. Allow the server to complete migration before serving traffic. For large databases, schedule maintenance downtime.

Problem: "The device time drift is ${timeDrift}ms"

Cause: Client clock is out of sync with the server beyond MAX_TIME_DRIFT threshold.

Resolution:

1. Sync client system clock via NTP
2. If time drift checking is problematic, set MAX_TIME_DRIFT=0 on the server to disable it (reduces replay attack protection)

Tip

On Docker deployments, the container's clock inherits from the host. If the host clock drifts (common in VMs that suspend/resume), restart the container or sync the host clock.

Problem: "CSRF token is missing" / "Invalid CSRF token"

Cause: State-changing request lacks a valid CSRF token.

Resolution: Ensure the client obtains a CSRF token from the session creation response and includes it in subsequent requests. API clients using session auth must handle CSRF; token-based auth (API keys) may bypass CSRF depending on server configuration.

Problem: "Invalid or missing session"

Cause: Request lacks authentication or uses an invalid session token.

Resolution:

1. Re-authenticate via POST /api/sessions
2. Verify the session token is included in request headers
3. Check that the user account is not disabled

Problem: "Your session has expired"

Cause: Session exceeded its TTL.

Resolution: Re-authenticate. Consider adjusting session TTL in server configuration for environments where long-lived sessions are acceptable.

Caution

Extending session TTL increases the window of vulnerability if a session token is compromised. Balance usability against security requirements.

Problem: "This account is disabled"

Cause: Administrator disabled the user account.

Resolution: An admin must re-enable the account via PATCH /api/users/:id or the admin web interface.

Problem: "SAML support is disabled"

Cause: SAML SSO is not configured on the server.

Resolution: Enable SAML in server configuration. SAML requires Identity Provider metadata, assertion consumer service URL, and entity ID configuration.

10.2 Sync Issues

Problem: Sync conflict — duplicate notes appear

Cause: The same note was modified on two devices before either synced.

Resolution: Joplin creates conflict notes (prefixed with "Conflict") to preserve both versions. Manually merge and delete the conflict copy. Reduce sync interval to minimize conflict window.

Problem: Sync stalls at "Downloading resources"

Cause: Large attachments or slow network.

Resolution:

1. Switch resource download mode to manual or auto
2. Reduce sync.maxConcurrentConnections on slow networks
3. Check for very large resources (> 100 MB) that may timeout

Problem: Sync fails with lock errors

Cause: A previous sync session did not release its lock (crash, timeout, network interruption).

Resolution: Locks have TTL-based expiration. Wait for the lock to expire, or manually clear stale locks via GET /api/locks and removing expired entries.

Problem: ErrorResyncRequired from server

Cause: Server state diverged too far from client state for delta sync.

Resolution: The client must perform a full resync. This happens automatically but may be slow for large accounts. Ensure adequate time and stable network for the full sync.

Problem: Sync to S3 fails with access denied

Cause: Incorrect S3 credentials or bucket permissions.

Resolution:

1. Verify access key and secret key
2. Ensure the bucket exists and the IAM user has read/write permissions
3. For non-AWS S3 providers (MinIO, Wasabi), verify the endpoint URL is correct
4. Check bucket region configuration

10.3 Client Issues

Problem: Search returns no results despite matching notes existing

Cause: Full-text search index is corrupted or not built.

Resolution:

1. Check db.ftsEnabled setting
2. Trigger a full reindex via Tools -> Rebuild search index (desktop)
3. Known issue #13322: search can crash with very old profile data — if reindex fails, export notes, create fresh profile, reimport

Warning

The search index rebuild can be slow for large note collections (10,000+ notes). It runs in the background but may impact UI responsiveness during the process.

Problem: OCR stops processing after a few resources

Cause: Known issue #14805 — OCR processing halts after approximately 5 resources.

Resolution: Restart the application to resume OCR processing. This is a known bug where the OCR queue stalls.

Problem: To-do reminders not firing

Cause: AlarmService requires platform-specific notification permissions.

Resolution:

1. Desktop: check system notification permissions for Joplin
2. Mobile: verify notification permissions in OS settings
3. Ensure the alarm time is set correctly (check timezone)

Problem: External editor changes not detected

Cause: ExternalEditWatcher relies on filesystem events that may not fire on network drives or certain filesystems.

Resolution:

1. Use a local filesystem for the Joplin data directory
2. Some editors write to a temporary file then rename — verify your editor's save behavior
3. Check that the editor setting points to the correct executable

Problem: Desktop application shows blank/white screen

Cause: Electron rendering failure, often caused by GPU driver issues.

Resolution:

1. Try launching with --disable-gpu flag
2. Update GPU drivers
3. Delete cache directory (%APPDATA%\joplin-desktop\Cache on Windows)

Problem: Mobile scroll rendering issues

Cause: Known issue #15141 — regression in scroll position calculation.

Resolution: Update to the latest mobile release. If the issue persists, switch between Markdown and WYSIWYG editor modes as a workaround.

Problem: Multi-window note focus issues (desktop)

Cause: Known issue #15106 — focus management across multiple Joplin windows.

Resolution: Click directly on the note editor to restore focus. This is a known UI bug in multi-window mode.

10.4 Encryption Issues

Problem: "Could not decrypt" errors on notes

Cause: Master key password not available for decryption.

Resolution:

1. Go to Encryption settings
2. Enter the master password for the listed master key
3. DecryptionWorker will process pending items in the background

Problem: E2EE enabled but sharing not working

Cause: PPK (Public-Private Key) not generated or exchanged.

Resolution:

1. Ensure both users have E2EE enabled
2. Verify PPK generation completed (check Encryption settings)
3. The sharing user must have the recipient's public key

Note

Notebook sharing with E2EE requires that both parties have completed the PPK key exchange. This happens automatically through the sync target but requires both users to sync after enabling E2EE.

Problem: Re-encryption requested but not completing

Cause: encryption.shouldReencrypt is set but the process stalled.

Resolution:

1. Ensure the application is running and syncing
2. Re-encryption processes items in batches during idle time
3. For large note collections, this can take hours — leave the application running

10.5 Build Issues

Problem: yarn install fails with workspace resolution errors

Cause: Yarn 4.9.2 workspace dependency resolution failure.

Resolution:

1. Delete .yarn/cache and node_modules in all packages
2. Run yarn install from the repository root
3. Ensure you are using Yarn 4.9.2 (check .yarnrc.yml)

Problem: OneNote converter WASM build fails

Cause: Missing Rust toolchain or wasm-pack.

Resolution:

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install wasm-pack
cargo install wasm-pack

# Build
cd packages/onenote-converter
wasm-pack build

Problem: Electron builder fails on Linux

Cause: Missing native dependencies for packaging.

Resolution:

# Ubuntu/Debian
sudo apt-get install -y rpm fakeroot dpkg

# For AppImage
sudo apt-get install -y libfuse2

Problem: React Native build fails (Android)

Cause: Android SDK or NDK configuration issues.

Resolution:

1. Verify ANDROID_HOME environment variable
2. Install required SDK platforms via Android Studio SDK Manager
3. For whisper-voice-typing: ensure NDK is installed and configured

Problem: React Native build fails (iOS)

Cause: CocoaPods or Xcode issues.

Resolution:

cd packages/app-mobile/ios
pod install --repo-update

Ensure Xcode command line tools are selected: xcode-select --install

10.6 Performance Issues

Problem: Slow startup with large note collection

Cause: SQLite database loading and index initialization.

Resolution:

1. Ensure SQLite WAL mode is active (Joplin sets this automatically)
2. Reduce revision retention (revisionService.ttlDays)
3. Archive old notebooks to reduce active note count

Tip

SQLite VACUUM can reclaim space after bulk deletions. Access via the Joplin developer console: await this.app().database().exec('VACUUM'). This locks the database briefly but can significantly reduce file size.

Problem: High memory usage during sync

Cause: Synchronizing many large resources simultaneously.

Resolution:

1. Reduce sync.maxConcurrentConnections to 1-2
2. Switch resource download mode to manual or auto
3. Increase Node.js heap size: --max-old-space-size=4096

Problem: Slow markdown rendering

Cause: Complex notes with many plugins enabled.

Resolution:

1. Disable unused markdown plugins (KaTeX, mhchem, etc.)
2. Split very long notes (> 10,000 words) into smaller notes
3. Disable WYSIWYG mode if not needed (Markdown mode is faster)

Appendix A: File API Implementations

Each sync target implements a FileApi interface:

Appendix B: Server Middleware Stack

The Koa middleware stack processes requests in order:

1. Error handler — catches exceptions, maps to ApiError subclasses
2. CORS — cross-origin request handling
3. Body parser — request body parsing (JSON, multipart)
4. CSRF protection — validates CSRF tokens for state-changing requests
5. Rate limiting — per-user/IP request throttling
6. Authentication — session validation, token verification
7. Route handler — business logic execution
8. Response — HTTP response formatting via Response class

Appendix C: Database Schema (Client SQLite)

Core tables in the client SQLite database:

Schema migrations are versioned and run automatically on application upgrade.

Appendix D: Environment Matrix

Appendix E: Known Issues Reference