Deploy Joplin Server with Dokploy

Dokploy is an open-source server management platform that simplifies deploying Docker Compose applications on your VPS. It handles reverse proxy configuration, SSL certificates, and deployment management — making it straightforward to run Joplin Server as a sync backend for your Joplin note-taking clients.

This guide walks you through deploying Joplin Server with a PostgreSQL database, persistent storage for notes and attachments, and automatic HTTPS.

Prerequisites

• A VPS with at least 1 vCPU, 2 GB RAM, and 10 GB storage
• Dokploy installed and running on your server (installation docs)
• A domain name (e.g., joplin.yourdomain.com) with DNS A record pointing to your server's IP

Docker Compose Configuration

Create a new Compose project in Dokploy and paste the following configuration:

version: "3.8"

services:
  joplin:
    image: joplin/server:latest
    restart: unless-stopped
    ports:
      - "22300:22300"
    environment:
      - APP_PORT=22300
      - APP_BASE_URL=https://${JOPLIN_DOMAIN}
      - DB_CLIENT=pg
      - POSTGRES_HOST=joplin-db
      - POSTGRES_PORT=5432
      - POSTGRES_DATABASE=joplin
      - POSTGRES_USER=joplin
      - POSTGRES_PASSWORD=${JOPLIN_DB_PASSWORD}
    depends_on:
      joplin-db:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:22300/api/ping || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

  joplin-db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_DB=joplin
      - POSTGRES_USER=joplin
      - POSTGRES_PASSWORD=${JOPLIN_DB_PASSWORD}
    volumes:
      - ../files/joplin-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U joplin"]
      interval: 10s
      timeout: 5s
      retries: 5

Note: Joplin Server stores note content and attachments in the PostgreSQL database by default. The APP_BASE_URL must match your public domain with HTTPS for proper sync URL generation in clients.

Environment Variables

Set these in Dokploy's Environment tab for your compose project:

Variable	Purpose	Example
JOPLIN_DOMAIN	Your Joplin Server domain	joplin.yourdomain.com
JOPLIN_DB_PASSWORD	PostgreSQL database password	a-strong-random-password

In Dokploy, environment variables are set via the Environment editor in the project settings. Do not create a .env file manually — Dokploy manages this for you.

Volumes & Data Persistence

This setup uses Dokploy's ../files convention for bind-mounted volumes:

• ../files/joplin-db-data — PostgreSQL database files containing all notes, notebooks, tags, and attachments

The ../files path is relative to the compose file inside Dokploy's project directory. This ensures your data persists across redeployments. Avoid using absolute paths (e.g., /opt/joplin) because Dokploy may clean them during redeployment.

Joplin Server stores all data (notes, attachments, metadata) directly in PostgreSQL, so the database volume is the critical persistence layer. Regular PostgreSQL backups are recommended.

Domain & SSL Setup

1. In your Dokploy project, navigate to the Domains tab
2. Click Add Domain and enter your domain (e.g., joplin.yourdomain.com)
3. Set the container port to 22300
4. Enable HTTPS — Dokploy automatically provisions a Let's Encrypt SSL certificate
5. Save and wait for the certificate to be issued (usually under a minute)

Dokploy's built-in Traefik reverse proxy handles TLS termination and routes traffic to your Joplin Server container. HTTPS is required for Joplin clients to sync securely.

Verifying the Deployment

1. In Dokploy, go to your project's Deployments tab and click Deploy
2. Watch the build logs — you should see both joplin and joplin-db containers start
3. Check the Logs tab for the joplin service. Look for: App started with the port number
4. Open https://joplin.yourdomain.com in your browser — you should see the Joplin Server login page
5. Log in with the default admin credentials: admin@localhost / admin — change these immediately
6. Configure your Joplin desktop or mobile clients to sync with https://joplin.yourdomain.com

Troubleshooting

Joplin clients fail to sync with "Could not connect" error Verify that APP_BASE_URL matches your domain exactly with https://. The sync URL in Joplin clients should be https://joplin.yourdomain.com. Ensure the server is accessible and SSL is working.

Default admin login doesn't work The default credentials are admin@localhost with password admin. These are only set on first initialization. If you've previously deployed with a different database, the existing credentials persist. Check the database or reset by removing the joplin-db-data volume.

Database migration errors on startup Joplin Server runs migrations automatically on startup. If migrations fail, check the PostgreSQL version compatibility and ensure the database is accessible. Review the joplin service logs for specific migration error messages.

SSL certificate not issuing Ensure your domain's DNS A record points to your server's IP and has propagated. Dokploy uses Let's Encrypt HTTP-01 challenges, so port 80 must be accessible. Check Traefik logs in Dokploy for certificate-related errors.

---

Learn more about Joplin in our complete overview.

Need a VPS? Hostinger VPS starts at $4.99/mo — perfect for running Joplin.

---

For more on Docker Compose deployments in Dokploy, see the Dokploy Docker Compose documentation.

App data sourced from selfh.st open-source directory.