How to Host a Joplin Server with Docker on Ubuntu

Updated on July 14, 2022
How to Host a Joplin Server with Docker on Ubuntu header image


Joplin Server is a free, self-hosted open-source note-taking and to-do application that captures ideas as notes, organizes them and synchronizes them to devices. This article explains how to host a Joplin Server with Docker on a Vultr Ubuntu server and synchronize it with a Joplin client application.


Before you begin, you'll need to do the following steps:

1. Install Joplin Server

  1. Create a new directory to store Joplin docker files in the /opt directory.

     $ sudo mkdir /opt/joplin
  2. Switch to the directory.

     $ cd /opt/joplin/
  3. Use a text editor to create a new Joplin Docker Compose file.

     $ sudo nano joplin-docker-compose.yml
  4. Add the following contents to the file.

    • The values 5434 and 8080 are examples. You can change these if required.

    • Replace with your fully-qualified domain name.

    • Replace the values for POSTGRES_PASSWORD, POSTGRES_DATABASE, and POSTGRES_USER with your preferred values.

        version: '3'
            image: postgres:13
            - ./data/postgres:/var/lib/postgresql/data
            - "5432:5432"
          restart: always
            - POSTGRES_PASSWORD=Your-Password-here
            - POSTGRES_USER=joplin-user
            - POSTGRES_DB=joplindb
            image: joplin/server:latest
          container_name: joplin-server
            - db
            - "8080:8080"
          restart: always
            - APP_PORT=8080
            - APP_BASE_URL=
            - DB_CLIENT=pg
            - POSTGRES_PASSWORD=Your-Password-here
            - POSTGRES_DATABASE=joplindb
            - POSTGRES_USER=joplin-user
            - POSTGRES_PORT=5432
            - POSTGRES_HOST=db

    This Docker Compose configuration creates a new Postgres database container and a Joplin Server listening on port 8080.

  5. Save and close the file.

  6. Start the Joplin Server.

     $ sudo docker-compose -f joplin-docker-compose.yml up -d
  7. Verify that Joplin Server is up and running.

     $ sudo docker ps

    You should see an output similar to the example below.

     CONTAINER ID   IMAGE                  COMMAND                  CREATED         STATUS         PORTS                                       NAMES
     143a9e9cdaa5   joplin/server:latest   "tini -- node dist/a…"   2 minutes ago   Up 4 seconds>8080/tcp, :::8080->8080/tcp   joplin-server
     1e55ccad2d52   postgres:13            "docker-entrypoint.s…"   2 minutes ago   Up 2 minutes>5432/tcp, :::5432->5432/tcp   joplin_db_1

2. Configure Nginx as a Reverse Proxy

  1. Create a new Nginx configuration file.

     $ sudo nano /etc/nginx/conf.d/joplin-server.conf
  2. Add the following contents to the file.

     server {
       listen 80;
       listen [::]:80;
       error_log /var/log/nginx/joplin-server.error;
       location / {
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
  3. Save and close the file.

  4. Verify the syntax and test Nginx for configuration errors.

     $ sudo nginx -t
  5. Restart Nginx to load changes.

     $ sudo service nginx restart

3. Security

By default, UFW is active on Ubuntu. Here's how to configure the firewall to allow HTTP and HTTPS access on the server.

  1. Allow HTTP access on port 80.

     $ sudo ufw allow 80/tcp
  2. Allow HTTPS access on port 443.

     $ sudo ufw allow 443/tcp
  3. Reload the Firewall rules to apply the changes.

     $ sudo ufw reload

4. Configure HTTPS Access

  1. Install the Certbot Let's Encrypt client.

     $ sudo apt install python3-certbot python3-certbot-nginx -y
  2. Request a free SSL certificate. Replace with your fully-qualified domain name, and with your email address.

     $ sudo certbot -d -m 

    Certbot will request a new certificate, install it for your Nginx server, and set up an automatic renewal event. See our Certbot guide to learn more.

  3. Restart Nginx to apply the changes.

     $ sudo service nginx restart

5. Access the Joplin Server

  1. Using a web browser, visit your subdomain to test the Joplin server.
  2. Log in to the Joplin server with the following default email and password.

    • Email: admin@localhost
    • Password: admin
  3. Click your username, Admin, in the top right corner.

  4. Edit your Administrator profile by filling in the Full name, Email, and Password fields. To ensure Joplin server security, enter a strong, hard-to-guess password and click Update Profile.

  5. Click Admin on the main top bar navigation menu.

  6. Navigate to Users, then click Add user to set up a new non-administrative account to sync with your Joplin Client.

  7. Complete the user form and click Create user to save the new account.

    Create a new Joplin Server User account

6. Connect Joplin Clients to the Joplin Server

Joplin has clients available for desktop and mobile devices.

  1. Install the Joplin client application from the official website.

  2. Launch the Joplin client.

    • Mac users should select the Preferences menu.
    • Windows users select the Settings menu.
    • Mobile users select the Configuration menu.
  3. Navigate to the Synchronisation section.

  4. Click the Synchronisation target dropdown.

    Joplin Client Synchronization with Server

  5. Select Joplin Server from the list.

  6. Enter your fully-qualified domain name in the Joplin Server URL field.

  7. Enter your account email address in the Joplin Server email field.

  8. Enter your password in the Joplin Server password field.

  9. Set your preferred timing in the Synchronisation interval field.

  10. Save your changes.

    • Desktop users click Apply.
    • Mobile users tap Check Synchronization Configuration.

7. Troubleshooting

You can test the Joplin Server host port from the command line with curl.

$ curl

Here are some common issues you may encounter, and how to handle them.

Bad Gateway

You may see this error:

502 Bad Gateway

Confirm that the Joplin Server container is running and listening on the port assigned in your Docker Compose file. As an example, this article uses port 8080. Make sure Joplin Server is running on Docker and listening on the host port.

Invalid origin on

You may see an error message such as:

Invalid origin:

Check the Docker logs for issues if you see this error.

$ sudo docker logs joplin-server

Not a valid URL

Another error you may see from the Joplin client is:

Error. Please check that URL, username, password, etc. are correct and that the sync target is accessible. The reported error was:
Not a valid URL:

To fix this error, add https:// at the beginning of the URL, and verify you've used the correct username and password.

Invalid origin on fully-qualified domain name

Another error you may see is:

Invalid origin:

Check the - APP_BASE_URL= environment variable in the Joplin Docker Compose file and verify the correct domain name is used to access the application. The correct variable should look like the one below. Replace with your fully-qualified domain name.


More Information


You have successfully hosted Joplin Server with Docker on Ubuntu and synchronized it with a Joplin Client application. You can set up several user accounts and keep them in sync with the server.