# Joplin Server

> Sync server for Joplin note-taking app.

- Category: Productivity & Collaboration
- Difficulty: intermediate
- Components: joplin-server, postgres
- Tags: joplin, notes, sync, markdown
- Source: https://docker.recipes/productivity/joplin-server

## Overview

Joplin Server is the official synchronization server for Joplin, an open-source note-taking and to-do application that supports markdown formatting, cross-platform sync, and end-to-end encryption. Originally developed as a desktop and mobile app, Joplin added server capabilities to enable users to host their own sync infrastructure rather than relying on cloud services like Dropbox or OneDrive. The server provides user management, note synchronization, sharing capabilities, and API access for multiple Joplin clients.

This deployment creates a complete Joplin sync infrastructure using two containers: the main Joplin server application and a dedicated PostgreSQL database. The Joplin service runs on port 22300 and connects to the PostgreSQL database for storing notes, metadata, user accounts, and synchronization state. The setup includes proper database connectivity configuration and persistent storage for the PostgreSQL data.

This configuration is ideal for individuals, families, or small teams who want complete control over their note synchronization without depending on third-party cloud services. It's particularly valuable for privacy-conscious users, organizations with data sovereignty requirements, or anyone wanting to extend Joplin's capabilities through the server's web interface and API access.

## Features

- Multi-user note synchronization with individual user accounts and authentication
- Web-based administration interface for user management and server configuration
- RESTful API for programmatic access to notes and synchronization endpoints
- Note and notebook sharing between users on the same server instance
- Support for Joplin's end-to-end encryption when configured in client applications
- PostgreSQL backend for reliable data storage and ACID transaction compliance
- Cross-platform client support for desktop, mobile, and terminal Joplin applications
- Markdown note rendering and search capabilities through the web interface

## Use cases

- Self-hosted note synchronization for privacy-conscious individuals and families
- Small team knowledge management with shared notebooks and collaboration
- Corporate environments requiring on-premises data storage for compliance
- Educational institutions providing note-taking infrastructure for students
- Development teams maintaining technical documentation and project notes
- Home lab enthusiasts building personal cloud services ecosystem
- Organizations migrating from commercial note-taking services to self-hosted solutions

## Prerequisites

- Docker and Docker Compose installed with container orchestration support
- Minimum 1GB RAM for PostgreSQL database and Joplin server operations
- Port 22300 available for Joplin server web interface and API access
- Environment variable DB_PASSWORD configured for database authentication
- Basic understanding of Joplin client configuration for server synchronization
- Web browser access for initial server setup and user management

## docker-compose.yml

```yaml
services:
  joplin:
    image: joplin/server:latest
    container_name: joplin
    restart: unless-stopped
    ports:
      - "22300:22300"
    environment:
      APP_BASE_URL: http://localhost:22300
      APP_PORT: 22300
      DB_CLIENT: pg
      POSTGRES_HOST: db
      POSTGRES_PORT: 5432
      POSTGRES_DATABASE: joplin
      POSTGRES_USER: joplin
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    container_name: joplin-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: joplin
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: joplin
    volumes:
      - joplin_db:/var/lib/postgresql/data

volumes:
  joplin_db:
```

## .env

```bash
DB_PASSWORD=changeme
```

## Usage notes

- Docs: https://joplinapp.org/help/apps/joplin_server/
- Access at http://localhost:22300 - default: admin@localhost / admin
- In Joplin app: Tools > Options > Sync > Joplin Server
- Enter server URL and generate API token from web UI
- Supports E2E encryption (configured in client)
- Share notes/notebooks with other users on same server

## Troubleshooting

- Connection refused on port 22300: Verify the joplin container started successfully and check Docker port mapping configuration
- Database connection failed: Ensure DB_PASSWORD environment variable matches between joplin and db services, and verify PostgreSQL container is running
- Joplin clients fail to sync: Check APP_BASE_URL matches the actual server address accessible to clients, and verify API tokens are generated correctly
- Admin login fails with default credentials: Reset admin password through the web interface or recreate the joplin container to restore defaults
- PostgreSQL data lost after container restart: Verify joplin_db volume is properly mounted and persistent storage is configured
- Slow synchronization performance: Increase PostgreSQL memory allocation and ensure adequate disk I/O for the database volume

