How to Install Joplin Server: Docker Compose Setup for Private Sync

Joplin Server is the official sync server for Joplin. Once you host your own instance, your notes can stay on your VPS, NAS, or home server, while your desktop and mobile clients sync without depending on a third-party cloud drive.

The easiest deployment method today is Docker Compose: one PostgreSQL container, one Joplin Server container, and a correctly configured APP_BASE_URL.

This guide is aimed at practical self-hosting on Ubuntu, Debian, CentOS, Synology, Unraid, OpenMediaVault, or any other environment that can run Docker.

Requirements

Before starting, prepare:

• a server or NAS that can stay online;
• Docker and Docker Compose;
• an internal IP if you only need LAN sync;
• a domain name and HTTPS reverse proxy if you need sync from outside your network;
• a real database password. Do not keep the sample password.

If you only sync between devices at home, http://LAN-IP:22300 is enough to get started. If you need external access from a phone or laptop, use Nginx Proxy Manager, Caddy, Traefik, or a similar HTTPS reverse proxy. Avoid exposing a plain HTTP service directly to the public internet.

Create a Joplin working directory

Create a dedicated directory for Joplin Server configuration and database data:

1
2

mkdir -p /data/joplin
cd /data/joplin

You can use another path, such as /opt/joplin or /volume1/docker/joplin. The important part is that the database directory must be persistent, so PostgreSQL data is not deleted with the container.

Write docker-compose.yml

Create the Compose file in the working directory:

1

nano docker-compose.yml

Paste this configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

version: '3.8'

services:
  db:
    image: postgres:16
    container_name: joplin-db
    restart: unless-stopped
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=joplin
      - POSTGRES_PASSWORD=change_this_database_password
      - POSTGRES_DB=joplin

  app:
    image: joplin/server:latest
    container_name: joplin-app
    depends_on:
      - db
    restart: unless-stopped
    ports:
      - "22300:22300"
    environment:
      - APP_PORT=22300
      - APP_BASE_URL=http://your-server-ip:22300
      - DB_CLIENT=pg
      - POSTGRES_USER=joplin
      - POSTGRES_PASSWORD=change_this_database_password
      - POSTGRES_DATABASE=joplin
      - POSTGRES_HOST=db
      - POSTGRES_PORT=5432

The two values you must change are:

• POSTGRES_PASSWORD: the database password. It must be identical in both the db and app services;
• APP_BASE_URL: the fixed address that Joplin clients will use to reach the server.

APP_BASE_URL is critical. It must be the address your clients can actually open:

• LAN only: http://192.168.1.10:22300
• public IP: http://your-public-ip:22300
• domain with HTTPS: https://joplin.example.com

If you later change the access address, update APP_BASE_URL and restart the service. Otherwise client sync, web redirects, or attachment links may behave oddly.

Start Joplin Server

Run this in the directory containing docker-compose.yml:

1

docker compose up -d

Check the containers:

1

docker compose ps

If the first startup takes a while, watch the logs:

1

docker compose logs -f

By default, Joplin Server listens on port 22300. Open your configured APP_BASE_URL in a browser. If the login page appears, the basic deployment is working.

First admin login

The default administrator account is:

1

admin@localhost

The default password is:

1

admin

After the first login, do one thing immediately: change the administrator password. Do not leave the default password on the server, especially if the service is reachable from the internet.

In the admin UI, open the Change Password page and replace admin with a strong password.

Create a daily sync account

Do not use the administrator account for daily note sync. A cleaner setup is to create a normal user and use that account on your desktop and mobile clients.

In the admin panel:

1. open Users;
2. click Add user;
3. enter the email and password you want to use;
4. create the user.

There is one common trap: if SMTP is not configured, Joplin Server will say it sent an activation email, but you will not receive it.

The workaround is simple:

1. go back to the admin panel;
2. open the Emails menu;
3. find the unsent activation email;
4. copy the activation link inside it;
5. open the link in a new browser tab to activate the account.

After activation, this normal user can be used for client sync.

Configure Joplin client sync

In the Joplin desktop or mobile app:

1. open Options or settings;
2. go to Synchronization;
3. select Joplin Server as the synchronization target;
4. enter your APP_BASE_URL in Joplin Server URL;
5. enter the activated normal user’s email in Email / Username;
6. enter that user’s password;
7. click Check sync configuration.

If the check passes, save the settings and start syncing.

If it fails, check these first:

• can the client open APP_BASE_URL in a browser?
• does APP_BASE_URL match the Compose file?
• has the normal user been activated?

Use HTTPS for external access

HTTP is usually fine for LAN-only use. For public access, use a reverse proxy and HTTPS.

Common options include:

• Nginx Proxy Manager;
• Caddy;
• Traefik;
• manual Nginx configuration.

When using a reverse proxy, APP_BASE_URL must be the final HTTPS address used by clients, for example:

1

- APP_BASE_URL=https://joplin.example.com

If you configure Nginx manually, pay attention to at least two things:

• increase the upload limit, for example client_max_body_size 100M;, otherwise notes with large attachments may fail to sync;
• forward Host, X-Forwarded-For, X-Forwarded-Proto, and related headers correctly, so Joplin Server can infer the right URL and protocol.

A simplified Nginx reverse proxy block:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

server {
    listen 443 ssl http2;
    server_name joplin.example.com;

    client_max_body_size 100M;

    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;
    }
}

With Nginx Proxy Manager, you usually only need to proxy the domain to port 22300 and enable an SSL certificate. Remember to change APP_BASE_URL in Compose to the HTTPS domain.

Common issues

APP_BASE_URL changes do not take effect

After editing docker-compose.yml, recreate the containers:

1

docker compose up -d

If it still behaves incorrectly, verify that the container environment variables have really changed. Editing the file alone is not enough if the service was not restarted.

Client sync reports a network error

Check these first:

• can your phone or computer open Joplin Server in a browser?
• is the reverse proxy certificate valid?
• is APP_BASE_URL the actual client-facing address?
• does the firewall allow 22300 or the HTTPS port?
• has the normal user been activated?

Large attachments fail to sync

If you access Joplin Server through Nginx or another reverse proxy, check the upload size limit first. Nginx defaults may be too small, so set:

1

client_max_body_size 100M;

Increase it further if your note attachments are larger.

Can I use it without SMTP?

Yes. For personal or family use, SMTP is not required. After creating a user, open the Emails page in the admin panel and copy the activation link manually.

For long-term team use, configure SMTP so registration, password resets, and notifications work properly.

Backup advice

The most important Joplin Server data is in PostgreSQL. In the example above, it is stored under:

1

/data/joplin/data/postgres

Back up this directory regularly, or use PostgreSQL pg_dump for database backups. Backing up only the Joplin Server container is not useful; the container can be pulled again, but the database contains your sync data.

The local clients also keep copies of your notes, but do not treat them as your only backup. A more robust setup is server database backup + local client copies + occasional JEX exports.

Summary

Joplin Server is not hard to deploy with Docker Compose. The real pitfalls are mostly these:

• APP_BASE_URL must be the real address used by clients;
• the default administrator password admin must be changed immediately;
• without SMTP, new users need to be activated from the Emails page in the admin panel.

For LAN use, http://IP:22300 is enough. For public access, use an HTTPS reverse proxy and increase the upload size limit. Once those details are handled, Joplin Server is a stable private note sync solution.

Sources

• Joplin Server Docker image
• Joplin Server Documentation