Author	Nejat Hakan
eMail	nejat.hakan@outlook.de
PayPal Me	https://paypal.me/nejathakan

Note Taking Joplin

Introduction Why Self-Host Joplin

Welcome to this comprehensive guide on self-hosting Joplin Server. Joplin is a powerful, open-source note-taking and to-do application with synchronization capabilities across multiple devices. While Joplin offers synchronization through commercial services like Dropbox or OneDrive, and its own Joplin Cloud service, self-hosting the Joplin Server component provides the ultimate control over your data, privacy, and features.

For university students, managing notes, research, and projects is crucial. Relying solely on third-party cloud services might raise concerns about data privacy, vendor lock-in, potential costs, or service limitations. Self-hosting empowers you to create your own private, secure, and potentially cost-effective note synchronization infrastructure.

Why would you, as a student, consider self-hosting Joplin Server?

1. Data Sovereignty and Privacy: Your notes often contain sensitive information, research data, personal thoughts, or project details. Self-hosting ensures your data resides entirely on infrastructure you control, eliminating reliance on third-party privacy policies which can change or may not align with your standards. You are the sole custodian of your data.
2. Control and Customization: You manage the server environment. This means you control update cycles, backup strategies, and resource allocation. While Joplin Server itself has limited customization, the underlying infrastructure (OS, reverse proxy, security measures) is yours to configure.
3. Learning Opportunity: Setting up and managing a web service like Joplin Server is an invaluable practical learning experience. It exposes you to concepts like server administration (Linux), containerization (Docker), networking (ports, firewalls), reverse proxies (Nginx, Traefik, Caddy), HTTPS/TLS encryption (Let's Encrypt), database management (PostgreSQL), and application maintenance (updates, backups). These are highly relevant skills in many technical fields.
4. Cost-Effectiveness (Potentially): While commercial cloud storage is often cheap initially, costs can increase with data volume. If you already have access to a server (perhaps a Raspberry Pi, an old computer, or a low-cost Virtual Private Server - VPS), the operational cost of self-hosting Joplin Server can be minimal, especially compared to dedicated note-syncing subscriptions like Joplin Cloud over the long term.
5. No Arbitrary Limits: Commercial services might impose limits on storage size, number of notes, attachment size, or API usage. With a self-hosted instance, the limits are primarily defined by the resources (disk space, RAM, CPU) of your server.
6. Reliability (Under Your Control): While commercial services strive for high uptime, outages can occur. With self-hosting, you control the server's uptime and maintenance schedule. While this means responsibility lies with you, it also means you're not subject to outages beyond your control.

What is Joplin Server?

It's important to distinguish between the Joplin application (the client you run on your desktop, phone, or terminal) and the Joplin Server.

• Joplin Client: The application used to create, edit, organize, and view notes and to-dos. It runs on Windows, macOS, Linux, Android, and iOS. There's also a terminal client.
• Joplin Server: A specific backend service developed by the Joplin team designed exclusively for synchronizing Joplin clients. It uses a PostgreSQL database to store note metadata, synchronization information, and user accounts. Attachments (like images or PDFs embedded in notes) are typically stored on the server's filesystem. It provides an API for clients to connect, push changes, and pull updates. It is not a general file synchronization service like Nextcloud or Dropbox; it's purpose-built for Joplin synchronization.

This guide will walk you through setting up, configuring, securing, and maintaining your own Joplin Server instance, categorized into basic, intermediate, and advanced sections, complete with practical workshops to solidify your understanding.

1. Basic Setup Getting Started

This section covers the fundamental steps required to get a basic Joplin Server instance up and running using Docker, the recommended deployment method. We'll focus on getting the server operational on your network and connecting your first client.

Prerequisites

Before diving into the installation, ensure you have the following prerequisites met. Understanding these components is crucial for a successful setup.

• A Server: This is the machine where Joplin Server will run. Options include:
  • Virtual Private Server (VPS): Services like DigitalOcean, Linode, Vultr, Hetzner Cloud offer affordable Linux servers accessible from anywhere. This is ideal if you need to sync notes outside your home network reliably. A low-tier VPS (e.g., 1 vCPU, 1-2 GB RAM, 20-30 GB SSD) is usually sufficient to start.
  • Home Server/Old Computer: An existing computer running Linux (like Ubuntu Server, Debian, CentOS) can host Joplin Server. This is cost-effective if you already have the hardware, but requires managing network access (port forwarding) if you need to sync from outside your home network.
  • Raspberry Pi: A Raspberry Pi (Model 3B+ or newer, ideally Pi 4/5 with 2GB+ RAM) can run Joplin Server, especially for personal use. Performance might be limited compared to a VPS or dedicated server, particularly during initial syncs with many notes or large attachments.
  • NAS Device with Docker Support: Some Network Attached Storage devices (e.g., Synology, QNAP) support Docker and can run Joplin Server. Check your NAS documentation.
  • Operating System: A Linux distribution is highly recommended (Ubuntu Server LTS or Debian are excellent choices). While Docker runs on Windows and macOS, deploying persistent server applications is typically more straightforward and resource-efficient on Linux. Familiarity with the Linux command line (Bash) is essential.
• Docker and Docker Compose: Joplin Server is officially distributed as a Docker image. Docker simplifies deployment by packaging the application and its dependencies into isolated containers.
  • Docker: The containerization platform. It allows you to run applications in isolated environments called containers. This ensures consistency across different machines and simplifies dependency management.
  • Docker Compose: A tool for defining and running multi-container Docker applications. Joplin Server requires a database (PostgreSQL), and Docker Compose allows you to define both the Joplin Server application container and the database container in a single configuration file (docker-compose.yml), making setup and management much easier.
  • Installation: You'll need to install both Docker Engine and Docker Compose on your server. Follow the official Docker documentation for your specific Linux distribution. Avoid using outdated versions from default distribution repositories if possible; use the official Docker repositories for the latest stable releases.
• Basic Networking Knowledge: Understanding IP addresses (what is your server's IP?), ports (Joplin Server uses a specific port, default is 22300), and potentially firewalls (ensuring the port is open) is necessary.
• Command Line Access: You will need SSH (Secure Shell) access or direct terminal access to your server to execute commands.

Installing Joplin Server using Docker Compose

Docker Compose is the most straightforward way to manage the Joplin Server and its required PostgreSQL database.

1. Connect to Your Server: Use SSH to connect to your server:

   ssh your_username@your_server_ip
   

   Replace your_username and your_server_ip accordingly.

2. Create a Directory for Joplin Server: It's good practice to keep configuration files organized.

   mkdir ~/joplin-server
   cd ~/joplin-server
   

3. Create the docker-compose.yml File: Create a file named docker-compose.yml using a text editor like nano or vim:

   nano docker-compose.yml
   

   Paste the following configuration into the file. Read the comments carefully and adjust values as needed.

   version: '3'
   
   services:
       db:
           image: postgres:13 # Use a specific supported version of PostgreSQL
           volumes:
               - ./joplin-data/postgres:/var/lib/postgresql/data # Persist database data on the host
           ports:
               # DO NOT expose the database port to the outside world unless absolutely necessary
               # and properly secured. Binding to 127.0.0.1 makes it accessible only from the host
               # (and other containers on the same Docker network).
               # Remove this 'ports' section entirely if only Joplin Server needs access.
               # - "127.0.0.1:5432:5432"
           restart: unless-stopped # Restart the database container if it stops unexpectedly
           environment:
               # Change these credentials! Use strong, unique passwords.
               POSTGRES_PASSWORD: your_postgres_password
               POSTGRES_USER: joplin
               POSTGRES_DB: joplin
           # Add healthcheck for better startup orchestration (optional but recommended)
           healthcheck:
             test: ["CMD-SHELL", "pg_isready -U joplin -d joplin"]
             interval: 10s
             timeout: 5s
             retries: 5
   
       app:
           image: joplin/server:latest # Use the official Joplin Server image
           depends_on:
               db:
                   # Wait for the database to be healthy before starting the app
                   condition: service_healthy
           ports:
               # Map host port 22300 to container port 22300
               # Format: <host_port>:<container_port>
               # Access Joplin Server via http://<your_server_ip>:22300
               - "22300:22300"
           restart: unless-stopped # Restart the app container if it stops unexpectedly
           environment:
               # !! IMPORTANT !!
               # Change APP_BASE_URL to the URL clients will use to reach the server.
               # For basic setup using IP and port, it looks like this.
               # Later, with a reverse proxy and HTTPS, it will be like https://joplin.yourdomain.com
               APP_BASE_URL: http://your_server_ip:22300
               APP_PORT: 22300 # The port the application inside the container listens on
   
               # Database configuration - MUST match the 'db' service environment variables
               DB_CLIENT: pg
               POSTGRES_PASSWORD: your_postgres_password # Use the SAME password as above
               POSTGRES_DATABASE: joplin # Use the SAME database name as above
               POSTGRES_USER: joplin # Use the SAME username as above
               POSTGRES_PORT: 5432 # Default PostgreSQL port
               POSTGRES_HOST: db # Docker Compose automatically resolves 'db' to the IP of the db service
   
               # Optional: Set the admin email and password directly (useful for scripting/automation)
               # If not set, you'll create the admin user via the web interface on first run.
               # JOPLIN_ADMIN_EMAIL: admin@example.com
               # JOPLIN_ADMIN_PASSWORD: your_admin_password
   

   Explanation of Key Parts:

   • version: '3': Specifies the Docker Compose file format version.
   • services:: Defines the different application components (containers).
     • db:: Defines the PostgreSQL database service.
       • image: postgres:13: Uses the official PostgreSQL image, version 13. Using a specific major version is generally safer than latest.
       • volumes: - ./joplin-data/postgres:/var/lib/postgresql/data: This is crucial. It maps a directory named joplin-data/postgres on your host machine (inside your ~/joplin-server directory) to the directory where PostgreSQL stores its data inside the container. This ensures your database data persists even if the container is removed or recreated.
       • restart: unless-stopped: Ensures the database container automatically restarts if it crashes or if the server reboots, unless you manually stop it.
       • environment:: Sets environment variables within the database container. POSTGRES_PASSWORD, POSTGRES_USER, POSTGRES_DB configure the initial database and user credentials. Choose strong, unique passwords.
       • healthcheck:: Defines a command Docker runs periodically to check if the database is ready to accept connections. This prevents the Joplin app from starting before the database is fully initialized.
     • app:: Defines the Joplin Server application service.
       • image: joplin/server:latest: Uses the official Joplin Server image. :latest pulls the most recent build. You might consider pinning to a specific version (e.g., joplin/server:2.8.1) for production stability.
       • depends_on: db: condition: service_healthy: Tells Docker Compose that the app service depends on the db service and should only start once the db service reports as healthy (based on the healthcheck).
       • ports: - "22300:22300": Maps port 22300 on your host server to port 22300 inside the Joplin Server container. This makes the server accessible via http://your_server_ip:22300.
       • restart: unless-stopped: Same restart policy as the database.
       • environment:: Sets environment variables for the Joplin Server application.
         • APP_BASE_URL: Critically important. This URL tells Joplin Server how it can be reached from the outside (by your clients). Initially, this will be your server's IP address and the port you exposed. You MUST change http://your_server_ip:22300 to reflect your server's actual IP address.
         • APP_PORT: The internal port the Joplin application listens on within the container. This usually matches the container port defined in the ports section.
         • DB_CLIENT: pg: Specifies that the database is PostgreSQL.
         • POSTGRES_* variables: Must match the credentials set in the db service exactly. POSTGRES_HOST: db works because Docker Compose provides internal DNS resolution; the app container can reach the db container using the service name db.

4. Start the Containers: Ensure you are in the ~/joplin-server directory (where your docker-compose.yml file is). Run the following command:

   docker-compose up -d
   

   • docker-compose up: Reads the docker-compose.yml file, pulls the necessary images (if not already present), creates and starts the containers defined within.
   • -d: Runs the containers in detached mode (in the background), so you get your terminal prompt back.

5. Verify the Containers are Running: Wait a minute or two for the containers to initialize, especially the database on the first run. Then, check their status:

   docker ps
   # or more detailed including logs
   docker-compose ps
   docker-compose logs -f # View logs in real-time (Ctrl+C to exit)
   

   You should see two containers listed, one for joplin-server_db_1 (or similar) and one for joplin-server_app_1, both with status Up. The database container might show Up (healthy). If you see Exit status, check the logs (docker-compose logs db or docker-compose logs app) for errors. Common initial errors involve incorrect passwords or database connection issues.

Initial Server Configuration

Once the containers are running, you need to perform the initial setup via the web interface.

1. Access the Web Interface: Open a web browser on your computer (or any device that can reach your server's IP address) and navigate to: http://your_server_ip:22300 (Replace your_server_ip with your server's actual IP address).

2. Create the Admin Account: You should be greeted by a Joplin Server setup screen asking you to create an admin account. If you didn't set the JOPLIN_ADMIN_EMAIL and JOPLIN_ADMIN_PASSWORD environment variables in your docker-compose.yml, you'll need to:

   • Enter your desired email address.
   • Enter a strong password and confirm it.
   • Click "Create Admin Account". If you did set the environment variables, you might be taken directly to the login screen. Use the credentials you defined in the docker-compose.yml file.

3. Log In: Log in using the admin credentials you just created or defined.

4. Explore the Admin Interface: Once logged in, you'll see the admin dashboard. Take a moment to look around:

   • Status: Shows basic server information and statistics.
   • Users: Allows you to create, manage, and delete regular user accounts (you'll likely create one for your personal use).
   • Config: Shows the current server configuration (mostly derived from environment variables). Changes here are usually not needed unless troubleshooting specific issues.
   • Tasks: Related to background server tasks.
   • Email: Configure SMTP settings if you want the server to send emails (e.g., for password resets, though this requires more setup).

5. Create a Regular User Account (Recommended): It's generally good practice not to use the admin account for your day-to-day note syncing.

   • Go to the "Users" section.
   • Click "Create User".
   • Enter an email address (can be the same or different from the admin) and a strong password for your personal Joplin client synchronization.
   • Click "Create".

Connecting Joplin Clients

Now, let's configure your Joplin desktop or mobile client to sync with your newly self-hosted server.

1. Open Joplin Client: Launch the Joplin application on your desktop or mobile device.
2. Go to Synchronization Settings:
   • Desktop (Windows/macOS/Linux): Go to Tools > Options (or Joplin > Preferences on macOS). Select the Synchronization tab on the left.
   • Mobile (Android/iOS): Go to Configuration (often accessed via a side menu or settings cog). Find the Synchronization section.
3. Select Synchronization Target: In the dropdown menu for the synchronization target, select Joplin Server (Beta). (Despite the "Beta" label, it's the standard option for self-hosted servers).
4. Enter Server URL: In the Joplin Server URL field, enter the exact APP_BASE_URL you configured in your docker-compose.yml file: http://your_server_ip:22300
5. Enter User Credentials:
   • Username/Email: Enter the email address of the regular user account you created in the Joplin Server admin interface (not the admin account, unless you intend to sync as admin, which is not recommended).
   • Password: Enter the password for that regular user account.
6. Check Synchronization Configuration: Click the "Check synchronization configuration" button. Joplin will attempt to connect to your server using the provided details.
   • Success: You should see a "Success! Synchronization configuration appears to be correct." message.
   • Failure: Double-check the Server URL (ensure it's the correct IP and port, and it starts with http://), email, and password. Ensure your server is running (docker ps) and that there isn't a firewall blocking port 22300 on the server or your client's network. Check the Joplin client logs (Help > Show Logs) and the server logs (docker-compose logs app) for more detailed error messages.
7. Apply Settings and Synchronize:
   • Click Apply or OK to save the settings.
   • The Joplin client should automatically start synchronizing. You can also manually trigger a sync by clicking the synchronize button (usually looks like circling arrows) in the main interface.
   • The first sync might take some time, especially if you already have many notes in the client.

You have now successfully set up a basic Joplin Server and connected a client!

Workshop Deploying Your First Joplin Server Instance

This workshop guides you through the practical steps of setting up the basic Joplin Server described above on a hypothetical Linux server.

Goal: Deploy Joplin Server using Docker Compose, create admin and user accounts, and connect a Joplin desktop client.

Prerequisites:

• Access to a Linux server (e.g., a VPS or a local Linux VM) with SSH access.
• Docker and Docker Compose installed on the server.
• Your server's public or local IP address.
• Joplin Desktop client installed on your computer.

Steps:

1. Connect to Your Server:

   # Replace user and IP with your actual details
   ssh student@192.168.1.100
   

2. Create Project Directory:

   mkdir ~/joplin-project
   cd ~/joplin-project
   pwd # Make sure you are in /home/student/joplin-project (or similar)
   

3. Create docker-compose.yml:

   nano docker-compose.yml
   

   Paste the following content into the editor. Important:
   • Replace your_strong_postgres_password with a unique, strong password.
   • Replace 192.168.1.100 in APP_BASE_URL with your server's actual IP address.

   version: '3'
   
   services:
       db:
           image: postgres:13
           volumes:
               - ./joplin-data/postgres:/var/lib/postgresql/data
           restart: unless-stopped
           environment:
               POSTGRES_PASSWORD: your_strong_postgres_password # CHANGE THIS!
               POSTGRES_USER: joplin
               POSTGRES_DB: joplin
           healthcheck:
             test: ["CMD-SHELL", "pg_isready -U joplin -d joplin"]
             interval: 10s
             timeout: 5s
             retries: 5
   
       app:
           image: joplin/server:latest
           depends_on:
               db:
                   condition: service_healthy
           ports:
               - "22300:22300"
           restart: unless-stopped
           environment:
               APP_BASE_URL: http://192.168.1.100:22300 # CHANGE THIS IP!
               APP_PORT: 22300
               DB_CLIENT: pg
               POSTGRES_PASSWORD: your_strong_postgres_password # Use the SAME password as above
               POSTGRES_DATABASE: joplin
               POSTGRES_USER: joplin
               POSTGRES_PORT: 5432
               POSTGRES_HOST: db
   

   Save the file and exit nano (Ctrl+X, then Y, then Enter).

4. Start Joplin Server:

   docker-compose up -d
   

   Docker will download the images (this might take a few minutes) and start the containers.

5. Verify Containers:

   sleep 60 # Wait a minute for initialization
   docker ps
   docker-compose ps
   

   You should see joplin-project_db_1 and joplin-project_app_1 running. The DB status might show (healthy).

6. Create Admin User (Web UI):

   • Open your web browser and go to http://<your_server_ip>:22300 (e.g., http://192.168.1.100:22300).
   • You should see the "Setup your Admin account" page.
   • Enter an email (e.g., admin@joplin.local) and a strong password.
   • Click "Create Admin Account".
   • Log in with these credentials.

7. Create Regular User (Web UI):

   • Inside the admin interface, click "Users" on the left sidebar.
   • Click "Create User".
   • Enter an email (e.g., student@joplin.local) and a strong password for your personal use.
   • Click "Create".

8. Configure Joplin Desktop Client:

   • Open your Joplin Desktop application.
   • Go to Tools > Options > Synchronization.
   • Select Joplin Server (Beta) as the target.
   • Enter the Joplin Server URL: http://<your_server_ip>:22300 (using your actual server IP).
   • Enter the regular user email (student@joplin.local in our example) and password you created in step 7.
   • Click "Check synchronization configuration". Verify you get the success message.
   • Click "Apply" or "OK".

9. Test Synchronization:

   • Create a new note or notebook in your Joplin client.
   • Click the "Synchronize" button (or wait for auto-sync).
   • Check the synchronization status in the bottom-left corner. It should complete successfully.
   • You can also check the server logs (docker-compose logs -f app on the server) to see sync activity.

Congratulations! You have deployed a functional Joplin Server instance and connected your client via your local network or server IP. This forms the foundation for more advanced configurations.

2. Intermediate Configuration Enhancing Your Setup

Now that you have a basic Joplin Server running, it's time to enhance its security, accessibility, and usability. This section focuses on setting up a reverse proxy, enabling HTTPS for secure connections, and understanding user management in more detail. These steps are crucial for exposing your server safely to the internet or even just for a more professional setup within your network.

Reverse Proxy Setup

Accessing your Joplin Server via http://<ip_address>:<port> works, but it's not ideal for several reasons:

• Security: Communication is unencrypted (HTTP). Anyone snooping on the network could potentially intercept your login credentials or note data during synchronization.
• Port Exposure: Exposing non-standard ports directly can be a security risk and might be blocked by some networks (like university or corporate firewalls).
• Accessibility: Remembering IP addresses and ports is inconvenient. Using a domain name (like joplin.yourdomain.com) is much cleaner.
• Scalability/Flexibility: A reverse proxy acts as a single entry point for web traffic, allowing you to host multiple services on the same server using different domain or sub-domain names, all typically listening on standard ports 80 (HTTP) and 443 (HTTPS).

A reverse proxy is a server that sits in front of one or more web servers (like your Joplin Server container), intercepting requests from clients and forwarding them to the appropriate backend server.

Popular Reverse Proxy Choices:

• Nginx: Highly performant, stable, and widely used. Excellent documentation available. Configuration is done via text files.
• Traefik: A modern reverse proxy designed with containers in mind. It can automatically discover services (like your Joplin container) and configure routing and SSL certificates, often simplifying setup, especially in dynamic Docker environments. Configuration can be via files (YAML/TOML) or Docker labels.
• Caddy: Known for its simplicity and automatic HTTPS configuration by default using Let's Encrypt. Configuration is typically done via a Caddyfile.

We will focus on Nginx here due to its prevalence and explicit configuration, which is good for learning.

Steps to Setup Nginx as a Reverse Proxy for Joplin Server:

1. Install Nginx: On your server (the same one running Docker), install Nginx using your distribution's package manager.

   # For Debian/Ubuntu
   sudo apt update
   sudo apt install nginx -y
   
   # For CentOS/RHEL based systems
   sudo dnf update
   sudo dnf install nginx -y
   

   Verify Nginx is running:

   sudo systemctl status nginx
   # Start/enable if necessary
   # sudo systemctl start nginx
   # sudo systemctl enable nginx # To start on boot
   

2. Modify docker-compose.yml (Optional but Recommended): Since Nginx will handle incoming connections on port 80/443, we no longer need to expose the Joplin Server port (22300) directly to the host's public interface. We only need Nginx (running on the host or in another container) to be able to reach it. Modify the ports section for the app service in your docker-compose.yml:

   # ... other parts of the file ...
   services:
     # ... db service ...
     app:
       # ... image, depends_on, restart ...
       ports:
         # Expose port 22300 ONLY to the host's loopback interface (127.0.0.1)
         # Nginx, running on the same host, can access it via 127.0.0.1:22300
         - "127.0.0.1:22300:22300"
         # Alternatively, REMOVE the 'ports' section entirely if Nginx runs in a container
         # on the same Docker network. In that case, Nginx would connect to 'app:22300'.
         # For simplicity with Nginx installed directly on the host, use 127.0.0.1 mapping.
       environment:
         # !! IMPORTANT !! Update APP_BASE_URL LATER when HTTPS is enabled.
         # For now, keep it as the IP/port for Nginx internal connection,
         # OR if you have DNS set up, you can potentially set it to
         # http://joplin.yourdomain.com (without HTTPS yet).
         # We will update this definitively in the HTTPS section.
         APP_BASE_URL: http://192.168.1.100:22300 # Or http://your_server_ip:22300
         # ... other environment variables ...
   # ... rest of the file ...
   

   Explanation: Binding to 127.0.0.1 (localhost) means port 22300 is only accessible from the server itself, not directly from the outside network. Nginx, running on the same server, can still connect to 127.0.0.1:22300. This enhances security by reducing the number of open ports exposed externally.

   After modifying the file, apply the changes:

   cd ~/joplin-project # Or your Joplin directory
   docker-compose up -d # This will recreate the 'app' container with the new port mapping
   

3. Configure Nginx: Nginx configurations are typically stored in /etc/nginx/sites-available/. We'll create a configuration file for your Joplin service. You'll need a domain name (or subdomain) pointing to your server's IP address for this to work properly, especially for the next step (HTTPS). Let's assume you have joplin.yourdomain.com.

   Create a new configuration file:

   sudo nano /etc/nginx/sites-available/joplin
   

   Paste the following configuration, adjusting server_name and proxy settings if needed:

   server {
       listen 80; # Listen on port 80 for HTTP traffic
       listen [::]:80; # Listen on port 80 for IPv6 HTTP traffic
   
       server_name joplin.yourdomain.com; # Replace with your actual domain/subdomain
   
       # Increase max body size to allow large attachments (e.g., 500MB)
       # Adjust as needed based on your expected attachment sizes
       client_max_body_size 500M;
   
       location / {
           # Forward requests to the Joplin Server container
           # It's listening on 127.0.0.1:22300 as configured in docker-compose.yml
           proxy_pass http://127.0.0.1:22300;
   
           # Set headers to pass correct information to Joplin Server
           proxy_set_header Host $host; # Pass the original host header
           proxy_set_header X-Real-IP $remote_addr; # Pass the client's real IP
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # Append proxy IP
           proxy_set_header X-Forwarded-Proto $scheme; # Pass the original scheme (http/https)
   
           # Recommended for WebSocket support if needed by future Joplin features
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
   
           # Increase proxy timeouts for potentially long sync operations
           proxy_connect_timeout 600s;
           proxy_send_timeout 600s;
           proxy_read_timeout 600s;
           send_timeout 600s;
       }
   
       # Optional: Access and error logs for this specific site
       access_log /var/log/nginx/joplin.access.log;
       error_log /var/log/nginx/joplin.error.log;
   }
   

   Explanation:

   • listen 80;: Tells Nginx to listen for incoming HTTP requests on port 80 for this server block.
   • server_name joplin.yourdomain.com;: Specifies which domain name this configuration applies to. Nginx uses this to route requests if you host multiple sites. Replace this with your actual domain/subdomain. You need to configure your DNS provider (where you bought the domain) to point this domain/subdomain to your server's public IP address.
   • client_max_body_size 500M;: Joplin notes can have attachments. This directive increases the maximum allowed size of a client request body, preventing errors when uploading large files. Adjust the size (e.g., 100M, 1G) as needed.
   • location / { ... }: This block applies to all requests for this domain.
   • proxy_pass http://127.0.0.1:22300;: This is the core directive. It tells Nginx to forward any incoming request to the Joplin Server running on 127.0.0.1 at port 22300.
   • proxy_set_header ...: These lines add or modify HTTP headers sent to the backend Joplin Server. This is crucial for Joplin Server to know the original client IP (X-Real-IP, X-Forwarded-For), the requested domain (Host), and whether the original connection was HTTPS (X-Forwarded-Proto, important later).
   • WebSocket headers (proxy_http_version, Upgrade, Connection): Included for future-proofing or potential features requiring real-time communication, though Joplin sync primarily uses standard HTTP requests.
   • Timeout directives (proxy_*_timeout, send_timeout): Increase default timeouts to prevent Nginx from closing connections during potentially long synchronization processes.
   • access_log, error_log: Defines specific log files for this site, making troubleshooting easier.

4. Enable the Nginx Site Configuration: Create a symbolic link from sites-available to sites-enabled:

   sudo ln -s /etc/nginx/sites-available/joplin /etc/nginx/sites-enabled/
   

   Remove the default Nginx site if it exists and conflicts (optional, but often recommended):

   sudo rm /etc/nginx/sites-enabled/default
   

5. Test Nginx Configuration: Always test your Nginx configuration before applying it:

   sudo nginx -t
   

   If it reports syntax is ok and test is successful, you are good to go. If not, carefully review the error message and your configuration file (/etc/nginx/sites-available/joplin).

6. Reload Nginx: Apply the new configuration without stopping the server:

   sudo systemctl reload nginx
   

7. Update DNS: Ensure your domain name (joplin.yourdomain.com) has an A record (for IPv4) or AAAA record (for IPv6) pointing to your server's public IP address. DNS changes can take time to propagate.

8. Test Access: Once DNS has propagated, try accessing your Joplin Server using the domain name in your browser: http://joplin.yourdomain.com You should see the Joplin Server login page. If it doesn't work, check Nginx logs (/var/log/nginx/joplin.error.log, /var/log/nginx/error.log) and ensure your DNS is pointing correctly.

You now have Nginx acting as a reverse proxy, making your Joplin Server accessible via a clean domain name on the standard HTTP port 80. The next crucial step is adding HTTPS.

Enabling HTTPS with Let's Encrypt

HTTPS (HTTP Secure) encrypts the communication between the client (your Joplin app) and the server (your reverse proxy). This is essential for protecting your login credentials and the content of your notes, especially when syncing over the internet.

Let's Encrypt is a free, automated, and open Certificate Authority (CA) that provides digital certificates needed for enabling HTTPS (TLS/SSL). Certbot is a client application that simplifies the process of obtaining and renewing Let's Encrypt certificates and configuring web servers like Nginx to use them.

Steps to Enable HTTPS using Certbot and Nginx:

1. Install Certbot and the Nginx Plugin: Certbot recommends using snapd for installation to ensure you get the latest version.

   # Install snapd if not already present
   sudo apt install snapd -y # Debian/Ubuntu
   # sudo dnf install snapd -y # Fedora/CentOS
   
   # Ensure snapd is up-to-date
   sudo snap install core; sudo snap refresh core
   
   # Remove any old OS packages for certbot
   sudo apt remove certbot # Debian/Ubuntu
   # sudo dnf remove certbot # Fedora/CentOS
   
   # Install Certbot using snap
   sudo snap install --classic certbot
   
   # Prepare the Certbot command for execution
   sudo ln -s /snap/bin/certbot /usr/bin/certbot
   
   # Install the Certbot Nginx plugin (might already be included)
   # Often snap install handles this, but check documentation if needed.
   # The main 'certbot' snap usually includes plugins for Apache/Nginx.
   

2. Obtain and Install the SSL Certificate: Run Certbot, telling it to use the Nginx plugin (--nginx) and specifying the domain name(s) you want to secure (-d joplin.yourdomain.com).

   # Make sure Nginx is running and port 80 is accessible from the internet
   # for the domain validation process.
   sudo systemctl status nginx
   
   # Run Certbot
   sudo certbot --nginx -d joplin.yourdomain.com
   

   Certbot will:

   • Ask for your email address (for urgent renewal and security notices).
   • Ask you to agree to the Let's Encrypt Terms of Service.
   • Ask if you're willing to share your email address with the EFF (optional).
   • Communicate with the Let's Encrypt server to verify you control the domain (usually by temporarily modifying your Nginx configuration to serve a challenge file).
   • If successful, obtain the SSL certificate.
   • Ask if you want to automatically redirect HTTP traffic to HTTPS (Recommended). Choose Redirect. Certbot will modify your Nginx configuration (/etc/nginx/sites-available/joplin) to handle HTTPS and the redirection.

3. Verify Automatic Renewal: Let's Encrypt certificates are valid for 90 days. The Certbot package automatically installs a systemd timer or cron job to attempt renewal twice a day. You can test the renewal process (without actually renewing unless it's due):

   sudo certbot renew --dry-run
   

   If the dry run succeeds, automatic renewal should work correctly.

4. Check Updated Nginx Configuration: Take a look at your Nginx configuration file again:

   sudo nano /etc/nginx/sites-available/joplin
   

   You'll notice Certbot has added lines similar to this:
   • listen 443 ssl; and listen [::]:443 ssl; to enable HTTPS on port 443.
   • ssl_certificate /etc/letsencrypt/live/joplin.yourdomain.com/fullchain.pem; path to your certificate.
   • ssl_certificate_key /etc/letsencrypt/live/joplin.yourdomain.com/privkey.pem; path to your private key.
   • Includes for SSL parameters (e.g., options-ssl-nginx.conf, ssl-dhparams.pem).
   • A separate server block listening on port 80 that permanently redirects (return 301) all HTTP traffic to the HTTPS version (https://$server_name$request_uri;).

5. Update Joplin Server APP_BASE_URL: This is a critical step. Joplin Server needs to know its public-facing URL, which is now HTTPS.

   • Edit your docker-compose.yml file:

     nano ~/joplin-project/docker-compose.yml
     

   • Find the APP_BASE_URL environment variable for the app service and update it:

     # ... inside the 'app' service environment section ...
     APP_BASE_URL: https://joplin.yourdomain.com # Use https and your domain
     # ... rest of the environment variables ...
     

   • Save the file and apply the change by recreating the Joplin Server container:

     cd ~/joplin-project # Or your Joplin directory
     docker-compose up -d # This restarts the 'app' container with the new environment variable
     

6. Test HTTPS Access:

   • Open your web browser and navigate to https://joplin.yourdomain.com.
   • You should see the Joplin Server login page, and your browser should show a padlock icon indicating a secure connection.
   • Try accessing the http:// version – you should be automatically redirected to https://.

7. Update Joplin Clients: Finally, update the synchronization settings in all your connected Joplin clients:

   • Go back to Tools > Options > Synchronization (or Configuration > Synchronization on mobile).
   • Change the Joplin Server URL from http://<ip_address>:<port> to your new HTTPS URL: https://joplin.yourdomain.com
   • Leave the username and password as they were.
   • Click "Check synchronization configuration" again to verify the connection over HTTPS.
   • Click "Apply" or "OK".
   • Trigger a synchronization to confirm it works with the new secure URL.

User Authentication and Management

With the basic setup, you created an admin user and potentially a regular user via the web interface. Let's delve deeper into user management.

• Admin User:
  • Created during initial setup or via environment variables (JOPLIN_ADMIN_EMAIL, JOPLIN_ADMIN_PASSWORD).
  • Has access to the /admin web interface (https://joplin.yourdomain.com/admin).
  • Can create, view, edit (passwords), and delete regular user accounts.
  • Can view server status and configuration.
  • Can technically be used for syncing notes, but this is not recommended for security and organizational purposes. Keep the admin account solely for administration.
• Regular Users:
  • Created via the admin interface.
  • Each user has their own separate set of notes and notebooks. Data is isolated between users.
  • Used for configuring the synchronization target in the Joplin clients.
  • Cannot access the /admin interface.
  • Password resets must currently be done by the administrator via the admin interface (unless email sending is configured, which is more advanced).

Managing Users via Admin Interface:

1. Access Admin Interface: Log in at https://joplin.yourdomain.com/admin with your admin credentials.
2. Navigate to Users: Click "Users" in the sidebar.
3. Create User: Click "Create User", fill in the email and password, and click "Create". Remember this password; you'll need it for the client setup.
4. Edit User (Reset Password): Click the "Edit" button next to a user's name. You can change the email address associated with the account or set a new password.
5. Delete User: Click the "Delete" button next to a user. Warning: This will permanently delete the user account and all associated synchronization data from the server. It does not delete the notes stored locally in the user's Joplin clients, but they will no longer be able to sync unless reconfigured with a different account/server.

Understanding Synchronization Mechanisms

Joplin's synchronization is designed to be robust and efficient. Here's a high-level overview:

• Metadata Database: The Joplin Server primarily stores metadata about your notes (titles, timestamps, notebook associations, tags, history), user accounts, and synchronization state in the PostgreSQL database.
• File System for Attachments: Attachments (images, PDFs, etc.) are typically stored directly on the server's filesystem within a specific directory managed by the Joplin Server container (this data resides within the Docker volume you mapped, e.g., ./joplin-data/).
• Delta Sync: Joplin clients don't upload or download everything on every sync. They use a delta synchronization mechanism. Clients keep track of changes locally and compare their state with the server's state. Only the changes (new notes, modified notes, deletions, new attachments) are transferred.
• Locking and Conflict Resolution: To handle situations where the same note might be edited on multiple clients simultaneously before syncing, Joplin Server uses a locking system and conflict resolution mechanisms. If a conflict occurs (e.g., the same note edited differently on two devices), Joplin often creates a "Conflict" copy of the note, allowing you to manually merge the changes later. This ensures no data is silently lost.
• End-to-End Encryption (E2EE): It's crucial to understand that Joplin Server itself does not encrypt the note content at rest on the server by default (beyond potential filesystem or database encryption you might set up separately). Joplin's End-to-End Encryption happens within the Joplin clients. If you enable E2EE in your Joplin client (Tools > Options > Encryption), your notes are encrypted on your device before being sent to the server. The server then stores the encrypted data. Only clients possessing the E2EE master password can decrypt the notes. This means even if your self-hosted server is compromised, the note content remains encrypted (assuming a strong master password). Enabling E2EE is highly recommended, especially when using any synchronization target, including your self-hosted server.

Workshop Securing Your Joplin Server with HTTPS and a Reverse Proxy

This workshop builds upon the basic setup, guiding you through configuring Nginx as a reverse proxy and securing it with a free Let's Encrypt SSL certificate.

Goal: Make your Joplin Server accessible via a secure domain name (https://joplin.yourdomain.com) instead of http://<ip_address>:<port>.

Prerequisites:

• Completed the "Basic Setup" workshop. Joplin Server running in Docker.
• A registered domain name (e.g., yourdomain.com).
• Ability to add DNS records for your domain.
• Your server's public IP address.
• Nginx installed on the server (sudo apt install nginx or similar).
• Certbot installed on the server (sudo snap install --classic certbot).

Steps:

1. Configure DNS:

   • Log in to your domain registrar or DNS provider's control panel.
   • Create an A record for a subdomain (e.g., joplin).
   • Point this A record to your server's public IP address.
   • Example: joplin.yourdomain.com A 198.51.100.10 (replace with your details).
   • Wait for DNS propagation (can take minutes to hours). You can check using ping joplin.yourdomain.com or dig joplin.yourdomain.com from your local machine or server.

2. Restrict Direct Port Access (Docker):

   • Edit the docker-compose.yml file:

     cd ~/joplin-project
     nano docker-compose.yml
     

   • Modify the ports section under the app service to bind to 127.0.0.1:

     # ... inside app service ...
     ports:
       - "127.0.0.1:22300:22300" # Only allow connections from the host
     # ...
     

   • Apply the change:

     docker-compose up -d
     

   • Verify you can no longer access http://<your_server_ip>:22300 directly from your browser (it should fail to connect).

3. Create Nginx Configuration:

   • Create the Nginx config file:

     sudo nano /etc/nginx/sites-available/joplin
     

   • Paste the following, replacing joplin.yourdomain.com with your actual domain:

     server {
         listen 80;
         listen [::]:80;
         server_name joplin.yourdomain.com; # CHANGE THIS
     
         client_max_body_size 500M;
     
         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;
             proxy_http_version 1.1;
             proxy_set_header Upgrade $http_upgrade;
             proxy_set_header Connection "upgrade";
             proxy_connect_timeout 600s;
             proxy_send_timeout 600s;
             proxy_read_timeout 600s;
             send_timeout 600s;
         }
     
         access_log /var/log/nginx/joplin.access.log;
         error_log /var/log/nginx/joplin.error.log;
     }
     

   • Save and close the file.

4. Enable Nginx Site and Test:

   sudo ln -s /etc/nginx/sites-available/joplin /etc/nginx/sites-enabled/
   sudo nginx -t # Check for syntax errors
   sudo systemctl reload nginx
   

5. Test HTTP Access via Domain:

   • Open your browser and go to http://joplin.yourdomain.com.
   • You should see the Joplin Server login page. If not, check DNS and Nginx logs.

6. Obtain SSL Certificate with Certbot:

   • Ensure your firewall allows traffic on port 80 (Certbot needs this for validation). sudo ufw status (if using ufw). sudo ufw allow 80/tcp.
   • Run Certbot:

     sudo certbot --nginx -d joplin.yourdomain.com
     

   • Follow the prompts: enter your email, agree to ToS, choose whether to share email (optional).
   • When asked about redirection, choose option 2: Redirect (Highly Recommended).
   • Certbot should confirm successful certificate deployment and configuration of redirection.

7. Update APP_BASE_URL in Docker Compose:

   • Edit the docker-compose.yml again:

     nano ~/joplin-project/docker-compose.yml
     

   • Update the APP_BASE_URL for the app service to use HTTPS:

     # ... inside app service environment ...
     APP_BASE_URL: https://joplin.yourdomain.com # CHANGE THIS to your domain
     # ...
     

   • Save the file and apply the change:

     docker-compose up -d
     

8. Test HTTPS Access:

   • Open your browser and navigate to https://joplin.yourdomain.com.
   • Verify the secure padlock icon is present.
   • Try http://joplin.yourdomain.com and confirm it redirects to https://.
   • Log in to the Joplin Server web interface via the HTTPS URL.

9. Update Joplin Client Configuration:

   • Open your Joplin Desktop client.
   • Go to Tools > Options > Synchronization.
   • Change the Joplin Server URL to https://joplin.yourdomain.com.
   • Click "Check synchronization configuration". Verify success.
   • Click "Apply"/"OK".
   • Perform a manual sync to test.

10. (Optional but Recommended) Enable E2EE:

    • In the Joplin client, go to Tools > Options > Encryption.
    • Click "Enable encryption".
    • Follow the steps to set a strong master password. Store this password securely (e.g., in a password manager) - if you lose it, your encrypted notes cannot be recovered!
    • Let Joplin encrypt your notes and sync the changes. Configure E2EE with the same password on all your other Joplin clients.

Congratulations! Your Joplin Server is now significantly more secure and professional, accessible via a standard HTTPS domain name.

3. Advanced Features Power User Techniques

With a secure and functional Joplin Server running, we can explore more advanced topics focusing on robustness, monitoring, automation, and understanding the server's capabilities more deeply.

Server Backups and Restoration Strategies

Data loss is unacceptable, especially for your valuable notes. Implementing a robust backup strategy for your self-hosted Joplin Server is non-negotiable. Relying solely on Docker volumes for persistence is insufficient protection against disk failure, accidental deletion (docker-compose down -v), or data corruption.

What needs backing up?

1. PostgreSQL Database: This contains all your note metadata, user accounts, synchronization state, tags, notebooks, etc. This is the most critical part.
2. Joplin Server Data Volume (Attachments): While the database holds metadata, the actual attachments (images, PDFs embedded in notes) might be stored on the filesystem within the Docker volume mapped for the app container, if you didn't configure external object storage (like S3). By default, Joplin Server stores attachments within the database as large objects (oid) rather than directly on the filesystem, simplifying backups as only the database needs backing up. Check your Joplin Server configuration or documentation for the version you are running to confirm the default attachment storage mechanism. If it uses the database (default), backing up PostgreSQL is sufficient. If it were configured to use the filesystem, you'd also need to back up that volume. Assuming the default database storage:
3. Configuration Files: Your docker-compose.yml file and any custom Nginx configuration files are important for quickly restoring your setup.

Backup Strategy Elements:

• Automation: Backups must be automated. Manual backups are easily forgotten. Use tools like cron on Linux.
• Frequency: How often should you back up? Depends on how frequently your notes change and how much data you're willing to lose. Daily backups are a good starting point for most users.
• Method:
  • Database Dump: Use the pg_dump utility to create a logical backup of the PostgreSQL database. This creates a SQL file that can be used to recreate the database structure and data. This is the most common and recommended method for Joplin Server.
  • Volume Snapshot/Backup: If using a VPS or specific filesystems (like ZFS), you might perform block-level snapshots of the Docker volumes. This can be faster but might require stopping the database for consistency, or rely on filesystem quiescing capabilities. pg_dump is generally safer for ensuring database consistency.
• Storage Location: Store backups externally! Keeping backups on the same server protects against application errors but not against hardware failure or server compromise.
  • Another Server/NAS: Use tools like scp or rsync to copy backups to another machine on your network.
  • Cloud Storage: Use tools like rclone, restic, or cloud provider CLIs (AWS CLI, gcloud) to upload encrypted backups to services like Backblaze B2, AWS S3, Google Cloud Storage, etc.
• Retention Policy: Decide how many old backups to keep (e.g., keep daily backups for 7 days, weekly for 4 weeks, monthly for 6 months). This prevents backups from consuming excessive storage space.
• Testing Restoration: Regularly test restoring your backups to a separate environment to ensure they are valid and you know the procedure. A backup is useless if it cannot be restored.

Implementing pg_dump Backups with Cron:

1. Create a Backup Script: Create a script, for example, ~/joplin-project/backup_joplin.sh:

   #!/bin/bash
   
   # Configuration - Adjust these paths and credentials
   BACKUP_DIR="/opt/joplin_backups" # Choose a directory OUTSIDE your joplin-project dir
   COMPOSE_FILE="/home/student/joplin-project/docker-compose.yml" # Path to your compose file
   DB_CONTAINER_NAME="joplin-project_db_1" # Find using 'docker ps' or 'docker-compose ps'
   DB_USER="joplin" # From your docker-compose.yml
   DB_NAME="joplin" # From your docker-compose.yml
   RETENTION_DAYS=7 # How many days of backups to keep
   
   # Create backup directory if it doesn't exist
   mkdir -p "$BACKUP_DIR"
   
   # Create timestamped backup filename
   TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
   BACKUP_FILE="$BACKUP_DIR/joplin_db_backup_$TIMESTAMP.sql.gz"
   
   echo "Starting Joplin DB backup to $BACKUP_FILE..."
   
   # Execute pg_dump inside the running database container
   # Use 'docker-compose exec' for convenience if script runs on the Docker host
   # -T db: Ensures it executes on the 'db' service defined in the compose file
   # -u postgres: Run the command as the 'postgres' user inside the container
   # pg_dump: The command to run
   # -U $DB_USER: The database user to connect as
   # -d $DB_NAME: The database name to dump
   # -Fc: Use custom format (good for large DBs, allows selective restore)
   # gzip: Pipe the output to gzip for compression
   docker-compose -f "$COMPOSE_FILE" exec -T db \
       pg_dump -U "$DB_USER" -d "$DB_NAME" -Fc | gzip > "$BACKUP_FILE"
   
   # Check if backup was successful (basic check: file exists and is not empty)
   if [ $? -eq 0 ] && [ -s "$BACKUP_FILE" ]; then
       echo "Backup successful: $BACKUP_FILE"
   
       # Prune old backups
       echo "Pruning backups older than $RETENTION_DAYS days..."
       find "$BACKUP_DIR" -name 'joplin_db_backup_*.sql.gz' -mtime +$RETENTION_DAYS -exec echo "Deleting {}" \; -exec rm {} \;
   
       # Optional: Add commands here to copy the backup offsite using scp, rsync, rclone etc.
       # Example using rsync to another server:
       # rsync -avz -e ssh "$BACKUP_FILE" user@backup-server:/path/to/remote/backups/
       # Example using rclone to cloud storage (requires rclone pre-configuration):
       # rclone copy "$BACKUP_FILE" remote_cloud:joplin-backups/
   
   else
       echo "ERROR: Backup failed!"
       # Optional: Add notification commands (e.g., send email)
       rm -f "$BACKUP_FILE" # Remove potentially corrupted file
       exit 1
   fi
   
   echo "Backup process finished."
   exit 0
   

   • Make the script executable: chmod +x ~/joplin-project/backup_joplin.sh

   • Explanation:

     • Sets variables for directories, container name, database credentials, and retention.
     • Creates the backup directory if needed.
     • Uses docker-compose exec -T db ... to run pg_dump inside the running db container. -T disables pseudo-tty allocation, necessary for piping data.
     • pg_dump -U $DB_USER -d $DB_NAME -Fc: Dumps the specified database using the specified user in custom format (-Fc). Custom format is generally preferred over plain SQL for flexibility.
     • | gzip > "$BACKUP_FILE": Pipes the output of pg_dump directly to gzip for compression and saves it to the timestamped backup file.
     • Includes basic success check and uses find to delete backups older than $RETENTION_DAYS.
     • Includes placeholders for offsite copy commands.

2. Schedule with Cron: Edit the crontab for your user (or root if preferred, adjusting paths):

   crontab -e
   

   Add a line to run the script daily (e.g., at 3:30 AM):

   # MIN HOUR DOM MON DOW COMMAND
   30 3 * * * /home/student/joplin-project/backup_joplin.sh >> /var/log/joplin_backup.log 2>&1
   

   • This runs the script every day at 3:30 AM.
   • >> /var/log/joplin_backup.log 2>&1: Appends both standard output and standard error from the script to a log file, useful for checking if backups ran correctly. Ensure the log directory/file is writable by the user running the cron job. You might need sudo touch /var/log/joplin_backup.log && sudo chown student:student /var/log/joplin_backup.log (replace 'student' if needed).

Restoring from a pg_dump Backup:

Restoration typically involves dropping the existing database (if necessary) and recreating it from the backup file. Always perform restoration on a test system first if possible, or ensure you have newer backups before attempting a restore on production.

1. Identify the Backup File: Choose the .sql.gz file you want to restore from (e.g., /opt/joplin_backups/joplin_db_backup_YYYYMMDD_HHMMSS.sql.gz).
2. Stop Joplin Server Application: Prevent syncs during restore.

   cd ~/joplin-project
   docker-compose stop app
   

3. Execute Restore: Use docker-compose exec to run pg_restore inside the db container.

   # Unzip the backup file and pipe it into pg_restore running inside the container
   gunzip < /opt/joplin_backups/joplin_db_backup_YYYYMMDD_HHMMSS.sql.gz | \
   docker-compose -f ~/joplin-project/docker-compose.yml exec -T db \
       pg_restore -U joplin -d joplin --clean --if-exists
   
   # OR, if you need to drop/recreate first (more thorough):
   # 1. Drop existing DB (careful!)
   # docker-compose -f ~/joplin-project/docker-compose.yml exec -T db dropdb -U joplin joplin
   # 2. Recreate DB
   # docker-compose -f ~/joplin-project/docker-compose.yml exec -T db createdb -U joplin -O joplin joplin
   # 3. Restore into the empty DB
   # gunzip < /opt/joplin_backups/joplin_db_backup_YYYYMMDD_HHMMSS.sql.gz | \
   # docker-compose -f ~/joplin-project/docker-compose.yml exec -T db \
   #     pg_restore -U joplin -d joplin
   

   • gunzip < backup_file.sql.gz: Uncompresses the backup file and sends its content to standard output.
   • | docker-compose exec -T db ...: Pipes the uncompressed SQL into the pg_restore command running inside the db container.
   • pg_restore -U joplin -d joplin: Restores the database named joplin using the joplin user.
   • --clean --if-exists: (Recommended flags for custom format restores) Tells pg_restore to drop existing database objects before recreating them. Useful for overwriting the current state with the backup state.

4. Restart Joplin Server Application:

   docker-compose start app
   

5. Verify: Check server logs and try syncing a client to ensure the restored state is correct.

Monitoring Joplin Server Health

Monitoring helps you proactively identify issues (e.g., server down, disk full, high resource usage) before they impact users.

Key Areas to Monitor:

• Container Status: Are the app and db containers running?
  • Command: docker ps, docker-compose ps
  • Automation: Simple script checking the output of docker ps for the expected containers.
• Resource Usage: Monitor CPU, RAM, and disk space usage on the host server and potentially within the containers.
  • Host: top, htop, df -h
  • Containers: docker stats (provides real-time CPU %, Mem Usage / Limit, Net I/O, Block I/O).
  • Automation: Tools like Prometheus with cadvisor can scrape detailed container metrics. Nagios/Icinga2 with plugins can monitor host resources. Simple scripts can parse df output to check disk space.
• Application Accessibility: Can clients actually reach the server?
  • Check Nginx status: systemctl status nginx
  • Check Joplin Server endpoint: Use curl to make a request to your server's health check endpoint (if available) or login page.

    # Check if the login page loads (expects a 2xx or 3xx redirect)
    curl -o /dev/null -s -w "%{http_code}\n" https://joplin.yourdomain.com/login
    # Check the API endpoint (requires admin credentials or specific token)
    # A simple check for reachability on the base URL might suffice:
    curl -o /dev/null -s -w "%{http_code}\n" https://joplin.yourdomain.com/api/ping # Check if this endpoint exists/responds
    

  • Automation: Monitoring systems (Prometheus Blackbox Exporter, Nagios check_http, Uptime Kuma) can periodically probe the URL.
• Log Files: Regularly review or automatically scan log files for errors.
  • Joplin App: docker-compose logs app
  • Database: docker-compose logs db
  • Nginx: /var/log/nginx/joplin.error.log, /var/log/nginx/error.log
  • Automation: Log aggregation tools (Loki, Elasticsearch/Fluentd/Kibana stack), simple grep scripts run via cron looking for "ERROR" or "FATAL".

Simple Monitoring Script Example (Cron):

Create ~/joplin-project/monitor_joplin.sh:

#!/bin/bash

COMPOSE_FILE="/home/student/joplin-project/docker-compose.yml"
JOPLIN_URL="https://joplin.yourdomain.com/login" # Change to your URL
ADMIN_EMAIL="admin@example.com" # Email to notify on failure

# Check container status
APP_RUNNING=$(docker-compose -f "$COMPOSE_FILE" ps -q app | xargs docker inspect -f '{{.State.Running}}' 2>/dev/null)
DB_RUNNING=$(docker-compose -f "$COMPOSE_FILE" ps -q db | xargs docker inspect -f '{{.State.Running}}' 2>/dev/null)

if [ "$APP_RUNNING" != "true" ] || [ "$DB_RUNNING" != "true" ]; then
    echo "ERROR: Joplin container(s) not running!" | mail -s "Joplin Monitor Alert: Container Down" "$ADMIN_EMAIL"
    # Optional: Attempt restart
    # echo "Attempting restart..."
    # docker-compose -f "$COMPOSE_FILE" restart
    exit 1
fi

# Check HTTP accessibility
HTTP_CODE=$(curl -o /dev/null -s -w "%{http_code}" --max-time 10 "$JOPLIN_URL")
if [ "$HTTP_CODE" -ne 200 ] && [ "$HTTP_CODE" -ne 301 ] && [ "$HTTP_CODE" -ne 302 ]; then
    echo "ERROR: Joplin URL $JOPLIN_URL returned HTTP code $HTTP_CODE!" | mail -s "Joplin Monitor Alert: URL Unreachable" "$ADMIN_EMAIL"
    exit 1
fi

# Check disk space on volume mount point (example: checks root '/')
# Adjust path based on where ./joplin-data actually resides if not /
THRESHOLD=90 # Alert if usage is above 90%
DISK_USAGE=$(df / | grep / | awk '{ print $5 }' | sed 's/%//g')
if [ "$DISK_USAGE" -gt "$THRESHOLD" ]; then
     echo "WARNING: Disk usage on / is at ${DISK_USAGE}% (Threshold: ${THRESHOLD}%)" | mail -s "Joplin Monitor Alert: Disk Space Low" "$ADMIN_EMAIL"
     # Note: This might not accurately reflect Docker volume usage if on a separate partition.
     # More specific check might be needed depending on setup.
fi

echo "Joplin Monitor: All checks passed."
exit 0

• Make executable (chmod +x).
• Configure mail command (e.g., install mailutils or ssmtp and configure it to send email).
• Schedule with crontab -e (e.g., run every 15 minutes).

For more robust monitoring, consider dedicated tools like Prometheus + Grafana + Alertmanager or Uptime Kuma.

Exploring Joplin Server API

Joplin Server exposes an HTTP API that the clients use for synchronization. While primarily for internal client use, understanding its existence can be useful.

• API Endpoint: Typically located at /api relative to your APP_BASE_URL (e.g., https://joplin.yourdomain.com/api).
• Authentication: API requests usually require authentication, typically session-based (after logging in via /login) or potentially token-based for specific integrations (less common for standard sync).
• Functionality: Includes endpoints for checking server status (/api/ping), getting/setting items (notes, notebooks, tags), managing resources (attachments), and handling synchronization logic.
• Documentation: The best source for API details is often the Joplin Server source code or specific documentation released by the Joplin team if available. It's not typically intended for extensive third-party use, unlike APIs from services like GitHub or Twitter.
• Potential Uses (Advanced/Experimental):
  • Creating custom scripts to add notes automatically.
  • Building custom dashboards (though the admin interface provides basic stats).
  • Integration with other services (requires careful handling of authentication and understanding the API specifics).

Direct interaction with the sync API is generally not recommended unless you are developing Joplin itself or have a very specific, well-understood need, as incorrect API calls could potentially corrupt your synchronization state.

Customization and Theming

Joplin Server itself offers very limited customization:

• Server Name: You might see the server name reflected in some client interfaces (often derived from the URL).
• Configuration: Primarily done via environment variables in docker-compose.yml as shown before.

The visual customization and theming heavily apply to the Joplin Clients (Desktop, Mobile), which support custom CSS. You can modify the appearance of the client application extensively using a userchrome.css file for UI elements and userstyle.css for the note rendering area. This customization happens entirely client-side and does not involve the self-hosted server.

Scaling Considerations

For the vast majority of personal or small-team use cases, a single Joplin Server instance running on a modest VPS or home server is perfectly adequate. However, understanding potential bottlenecks is useful:

• Database Performance: The PostgreSQL database is the most likely bottleneck under heavy load (many users syncing frequently, very large note histories). Scaling involves:
  • Vertical Scaling: Increasing server resources (CPU, RAM, faster disk I/O) for the database container/host. Tuning PostgreSQL configuration (postgresql.conf).
  • Horizontal Scaling (Complex): Database replication or clustering. This adds significant complexity and is rarely needed for Joplin Server.
• Application Server Resources: The Joplin Server app container itself uses CPU and RAM. If monitoring shows consistent high usage, increasing resources allocated to the Docker container or moving to a more powerful host (vertical scaling) is the primary approach.
• Network Bandwidth: Synchronization involves data transfer. If you have many users or very large attachments, ensure your server has sufficient network bandwidth.
• Load Balancing (Overkill for most): If you had an extremely large number of users, you might consider running multiple app container instances behind a load balancer (like Nginx or Traefik), all connecting to the same PostgreSQL database. This adds complexity in managing shared state and potential attachment storage.

In practice, for personal use, focus on:

1. Providing adequate RAM (2GB+ recommended for server + DB).
2. Using SSD storage for the database volume.
3. Ensuring reliable network connectivity.

Workshop Implementing Automated Backups and Basic Monitoring

This workshop focuses on setting up the automated database backup script and a simple cron job to monitor container status and URL accessibility.

Goal: Automate daily backups of the Joplin database and receive email alerts if the server becomes unresponsive or containers stop.

Prerequisites:

• Completed the Intermediate workshop (Joplin running via HTTPS domain).
• Access to the server hosting Joplin.
• A designated directory for backups (e.g., /opt/joplin_backups).
• A way to send email from the server (e.g., mailutils installed: sudo apt install mailutils). You might need further configuration (like ssmtp) for emails to reach external addresses reliably. Test sending mail first: echo "Test body" | mail -s "Test Subject" your_email@example.com.
• Your Joplin Server domain name and admin email address.

Steps:

1. Create Backup Directory:

   sudo mkdir /opt/joplin_backups
   # Set permissions - allow your user (e.g., 'student') to write here
   # Or run the backup script as root if easier
   sudo chown $(whoami):$(whoami) /opt/joplin_backups
   ls -ld /opt/joplin_backups # Verify ownership/permissions
   

2. Create Backup Script:

   • Navigate to your Joplin project directory: cd ~/joplin-project
   • Create the script file: nano backup_joplin.sh
   • Paste the script content from the "Server Backups and Restoration Strategies" section above.
   • Carefully review and adjust the configuration variables at the top:
     • BACKUP_DIR="/opt/joplin_backups" (or your chosen directory)
     • COMPOSE_FILE="/home/student/joplin-project/docker-compose.yml" (verify path)
     • DB_CONTAINER_NAME=$(docker-compose -f $COMPOSE_FILE ps -q db) (Dynamically find name)
     • DB_USER="joplin"
     • DB_NAME="joplin"
     • RETENTION_DAYS=7 (adjust if desired)
   • Make the script executable: chmod +x backup_joplin.sh

3. Perform an Initial Manual Backup:

   • Run the script manually to test it:

     ./backup_joplin.sh
     

   • Check the output for success messages.
   • Verify a .sql.gz file was created in /opt/joplin_backups: ls -l /opt/joplin_backups

4. Schedule Backup with Cron:

   • Edit your user's crontab: crontab -e
   • Add the following line (adjust path to script and log file):

     # Run Joplin backup daily at 3:30 AM
     30 3 * * * /home/student/joplin-project/backup_joplin.sh >> /home/student/joplin-project/joplin_backup.log 2>&1
     

   • Save and close the editor. Verify the cron job is listed: crontab -l.

5. Create Monitoring Script:

   • Still in ~/joplin-project, create the monitoring script: nano monitor_joplin.sh
   • Paste the script content from the "Monitoring Joplin Server Health" section above.
   • Review and adjust variables:
     • COMPOSE_FILE="/home/student/joplin-project/docker-compose.yml" (verify path)
     • JOPLIN_URL="https://joplin.yourdomain.com/login" (replace with your actual URL)
     • ADMIN_EMAIL="your_alert_email@example.com" (replace with email for alerts)
   • Make the script executable: chmod +x monitor_joplin.sh

6. Perform an Initial Manual Monitor Run:

   • Run the script manually:

     ./monitor_joplin.sh
     

   • It should output "Joplin Monitor: All checks passed." if everything is okay.
   • Test failure: Stop the app container (docker-compose stop app) and run ./monitor_joplin.sh again. It should now output an error and attempt to send an email. Check your inbox (and spam folder). Remember to restart the container: docker-compose start app.

7. Schedule Monitoring with Cron:

   • Edit your user's crontab again: crontab -e
   • Add a line to run the monitor script frequently (e.g., every 15 minutes):

     # Monitor Joplin server every 15 minutes
     */15 * * * * /home/student/joplin-project/monitor_joplin.sh >> /home/student/joplin-project/joplin_monitor.log 2>&1
     

   • Save and close. Verify with crontab -l.

You now have:

• Automated daily database backups stored locally with 7-day retention.
• A basic monitoring script running every 15 minutes that checks container status and URL accessibility, sending an email alert on failure.

Next Steps (Self-Study): Enhance the backup script to copy backups offsite (e.g., using rclone to cloud storage or rsync to another server). Explore more advanced monitoring tools like Uptime Kuma or the Prometheus/Grafana stack.

4. Maintenance and Troubleshooting Keeping it Running

Operating a self-hosted service requires ongoing maintenance and the ability to troubleshoot issues when they arise. This section covers updating Joplin Server, diagnosing common problems, and understanding logs.

Updating Joplin Server

Keeping your Joplin Server instance up-to-date is important for security patches, bug fixes, and new features. Thanks to Docker, the update process is generally straightforward.

Update Procedure:

1. Check for New Versions: Monitor the Joplin Server Releases page on GitHub: https://github.com/laurent22/joplin/releases. Read the release notes carefully, especially for any breaking changes or specific instructions related to the update.
2. Perform a Backup: Crucial step! Before any update, ensure you have a recent, verified backup of your database. Use the backup script created earlier or perform a manual backup.

   ~/joplin-project/backup_joplin.sh
   

3. Navigate to Your Compose Directory:

   cd ~/joplin-project # Or your Joplin directory
   

4. Pull the Latest Image: Instruct Docker Compose to pull the latest version of the image specified in your docker-compose.yml (e.g., joplin/server:latest or a specific version if you pinned it).

   docker-compose pull app
   

   If you are using :latest, this will download the newest build. If you pinned a version (e.g., image: joplin/server:2.8.1) and want to update to a newer one (e.g., 2.9.0), you need to edit the docker-compose.yml file first, changing the image tag, and then run docker-compose pull app.
5. Recreate the Application Container: Stop the current app container and start a new one using the freshly pulled image. Docker Compose handles this gracefully, preserving your volumes.

   docker-compose up -d --no-deps app
   

   • up -d: Ensures the service runs in detached mode.
   • --no-deps: Prevents Compose from unnecessarily recreating the database container (db) if it hasn't changed.
   • app: Specifies that only the app service should be updated.
6. Verify the Update:
   • Check container status: docker ps, docker-compose ps. Ensure the app container is running.
   • Check logs for errors during startup: docker-compose logs app
   • Access the Joplin Server web interface (https://joplin.yourdomain.com/admin) and check the "Status" page or look for version information to confirm the update was successful.
   • Test synchronization with a Joplin client.

Updating PostgreSQL: Updating the PostgreSQL database (db service) is less frequent and requires more care, as major version upgrades often involve data migration steps. Stick to minor version updates within the same major release (e.g., 13.x to 13.y) unless specifically required and you have thoroughly read the PostgreSQL upgrade documentation and Joplin Server compatibility notes. Minor PostgreSQL updates can often be done similarly by updating the image tag in docker-compose.yml (e.g., postgres:13.5 to postgres:13.6), pulling, and recreating the db container (docker-compose up -d --no-deps db), but always back up first. Major upgrades (e.g., 13 to 14) typically require a pg_upgrade process or dump/restore procedure.

Common Issues and Solutions

• Synchronization Failures:
  • Cause: Incorrect Server URL, username, or password in the Joplin client.
  • Solution: Double-check the Synchronization settings in the client (Tools > Options > Synchronization). Ensure the URL starts with https://, matches your domain, and credentials are correct for the regular user account. Click "Check synchronization configuration".
  • Cause: Server is down or unreachable.
  • Solution: Check server status (docker ps). Check Nginx status (sudo systemctl status nginx). Use curl https://joplin.yourdomain.com from the client machine or another external point to test connectivity. Check server logs (docker-compose logs app, Nginx error logs). Check firewall rules on the server (sudo ufw status) and any intermediate firewalls. Check DNS resolution (ping joplin.yourdomain.com).
  • Cause: Expired or invalid SSL certificate.
  • Solution: Check certificate validity in your browser when accessing the URL. Run sudo certbot certificates to check status. Run sudo certbot renew to attempt renewal (check logs if it fails, often due to port 80 being blocked).
  • Cause: Reverse proxy misconfiguration.
  • Solution: Test Nginx config (sudo nginx -t). Review Nginx logs (/var/log/nginx/joplin.error.log). Ensure proxy_pass points to the correct internal IP/port (127.0.0.1:22300) and required headers are set.
  • Cause: Client time/date incorrect. TLS/SSL connections often fail if the client's clock is significantly skewed.
  • Solution: Ensure the date, time, and timezone are set correctly on the client device.
  • Cause: Large sync operation timing out.
  • Solution: Check Nginx proxy timeout settings (proxy_read_timeout etc.) in your Nginx config. Check Joplin client logs for timeout errors. Ensure server has adequate resources.
  • Cause: Joplin Server application error.
  • Solution: Check Joplin Server logs (docker-compose logs app) for specific error messages (database connection issues, internal errors).
• Container Not Starting (Exit status in docker ps):
  • Cause: Port conflict (e.g., another service already using port 22300 on the host or 127.0.0.1).
  • Solution: Check which process is using the port (sudo ss -tulpn | grep 22300). Stop the conflicting service or change the host port mapping in docker-compose.yml (e.g., - "22301:22300") and update Nginx proxy_pass accordingly.
  • Cause: Incorrect environment variables in docker-compose.yml (e.g., database credentials mismatch).
  • Solution: Carefully review all environment variables, ensuring POSTGRES_PASSWORD matches between app and db services. Check APP_BASE_URL. Examine logs (docker-compose logs app or db) immediately after attempting to start for clues.
  • Cause: Database container (db) not healthy or ready when app starts.
  • Solution: Ensure depends_on: db: condition: service_healthy is present in the app service definition and that the db service has a working healthcheck. Check db logs (docker-compose logs db) for initialization errors.
  • Cause: Docker volume permission issues.
  • Solution: Less common with standard setup, but ensure the directories mapped as volumes (e.g., ./joplin-data/postgres) are writable by the user ID the container runs as (often handled automatically by Docker or the image entrypoint). Check container logs.
  • Cause: Corrupt data in the database or volume preventing startup.
  • Solution: Try restoring from a backup. Check database logs.
• Error 502 Bad Gateway (from Nginx):
  • Cause: The Joplin Server application container (app) is down, restarting, or unreachable by Nginx.
  • Solution: Check app container status (docker ps). Check app logs (docker-compose logs app) for crashes or errors. Ensure Nginx proxy_pass directive points to the correct address (http://127.0.0.1:22300 if Joplin port is mapped to localhost, or http://app:22300 if Nginx is in a container on the same Docker network). Check Docker networking.
• Error 504 Gateway Timeout (from Nginx):
  • Cause: The Joplin Server application took too long to respond to a request forwarded by Nginx. Common during very large syncs or if the server is under heavy load.
  • Solution: Increase timeout values (proxy_connect_timeout, proxy_send_timeout, proxy_read_timeout, send_timeout) in the location / { ... } block of your Nginx configuration. Reload Nginx (sudo systemctl reload nginx). Investigate server performance (CPU, RAM, I/O) using top, htop, docker stats. Check app logs for slow operations.
• Data Corruption:
  • Cause: Extremely rare, but could theoretically occur due to underlying disk issues, unclean shutdowns during writes, or bugs.
  • Solution: Restore from the most recent known good backup. This highlights the critical importance of regular, automated, and tested backups.

Log Analysis

Logs are your primary tool for diagnosing problems. Learn where they are and what to look for.

• Joplin Server Application Logs:
  • Command: docker-compose logs app (shows logs from the app container)
  • docker-compose logs -f app: Follow logs in real-time.
  • docker-compose logs --tail=100 app: Show the last 100 lines.
  • What to look for: ERROR messages, stack traces (multi-line error reports), database connection errors, permission denied errors, messages indicating specific failed operations (e.g., related to sync, user auth).
• PostgreSQL Database Logs:
  • Command: docker-compose logs db
  • What to look for: FATAL or ERROR messages related to startup, connection limits, disk space issues, data corruption warnings, slow queries (if enabled).
• Nginx Logs:
  • Access Log: /var/log/nginx/joplin.access.log (or as configured). Shows incoming requests, status codes (200 OK, 301 Redirect, 401 Unauthorized, 404 Not Found, 502 Bad Gateway, 504 Timeout), request times. Useful for seeing if requests are reaching Nginx and what the outcome is.
  • Error Log: /var/log/nginx/joplin.error.log (or as configured) and /var/log/nginx/error.log (global errors). Shows why Nginx couldn't process a request (e.g., connection refused when trying proxy_pass to backend, upstream timed out, SSL handshake errors, configuration syntax errors on reload). Check this first for 5xx errors.
• Docker Daemon Logs:
  • Command: sudo journalctl -u docker.service (on systemd systems)
  • What to look for: Errors related to starting/stopping containers, network issues, volume mounting problems, Docker daemon crashes. Less commonly needed for application-level issues but useful for infrastructure problems.
• System Logs:
  • Command: dmesg, sudo journalctl -xe, /var/log/syslog
  • What to look for: Kernel messages related to disk errors (I/O errors), memory issues (OOM killer), network interface problems.

Troubleshooting Workflow:

1. Identify the Symptom: What exactly is failing? (Sync error on client? Web UI inaccessible? 502 error?).
2. Check Client: Can the client reach other websites? Is the error specific to Joplin? Check client logs (Help > Show Logs).
3. Check Accessibility: Can you ping the server? Can you curl the Joplin URL (https://joplin.yourdomain.com)? Does it give the expected response or an error?
4. Check Nginx: If using a reverse proxy, check its status (systemctl status nginx) and error logs (/var/log/nginx/joplin.error.log). Test config (nginx -t).
5. Check Container Status: Are the app and db containers running (docker ps)?
6. Check Application Logs: Look at docker-compose logs app for specific errors around the time the issue occurred.
7. Check Database Logs: Look at docker-compose logs db if application logs suggest database issues.
8. Check Resources: Is the server out of disk space (df -h), RAM, or CPU (top, htop, docker stats)?
9. Reproduce and Isolate: Can you reliably reproduce the error? Does it happen on all clients or just one? Did it start after a specific change (update, configuration change)?
10. Consult Documentation/Community: Search the Joplin Discourse forum (https://discourse.joplinapp.org/) or GitHub issues for similar problems.

Workshop Performing a Server Update and Diagnosing a Sync Issue

This workshop simulates a Joplin Server update and then guides you through diagnosing a common synchronization problem.

Goal: Practice the safe update procedure for Joplin Server and learn how to use logs to troubleshoot a client connection error.

Prerequisites:

• Completed previous workshops. Joplin Server running and accessible via HTTPS.
• At least one Joplin client configured and syncing.
• Access to the server hosting Joplin.
• Backup script (backup_joplin.sh) available.

Part 1: Performing a Simulated Update

1. Check Current Version (Simulated):

   • Assume your docker-compose.yml currently uses image: joplin/server:2.8.1 (or some specific older version). You can check the running container image if needed: docker inspect $(docker-compose ps -q app) --format='{{.Config.Image}}'
   • Check the latest version on the Joplin Server Releases page. Let's pretend 2.9.0 is the latest stable release.

2. Perform Backup:

   cd ~/joplin-project
   ./backup_joplin.sh
   # Verify backup file created in /opt/joplin_backups
   

3. Update docker-compose.yml:

   • Edit the compose file: nano docker-compose.yml
   • Change the image line for the app service:

     # From:
     # image: joplin/server:2.8.1
     # To (or use :latest if you prefer):
     image: joplin/server:2.9.0 # Simulate updating to a new specific version
     

   • Save and close the file.

4. Pull the New Image:

   docker-compose pull app
   

   You should see Docker downloading the layers for the 2.9.0 image.

5. Recreate the Application Container:

   docker-compose up -d --no-deps app
   

   Docker will stop the old container and start a new one based on the 2.9.0 image.

6. Verify Update:

   • Wait 30-60 seconds.
   • Check container status: docker-compose ps (ensure app is Up).
   • Check logs briefly for startup errors: docker-compose logs --tail=50 app
   • Check the image version running: docker inspect $(docker-compose ps -q app) --format='{{.Config.Image}}' (should show joplin/server:2.9.0).
   • Open the admin interface (https://joplin.yourdomain.com/admin) and verify functionality. Look for version info if displayed.
   • Perform a sync from your Joplin client to ensure it still works after the update.

Part 2: Diagnosing a Sync Issue

1. Simulate the Problem (Client Side):

   • Open your Joplin Desktop client.
   • Go to Tools > Options > Synchronization.
   • Intentionally change the password to something incorrect.
   • Click "Apply" / "OK".
   • Trigger a manual synchronization (click the sync button).

2. Observe the Error (Client Side):

   • The synchronization should fail.
   • Look in the bottom-left corner or status area. You'll likely see an error message, possibly mentioning "Authentication failed", "Unauthorized", or a generic network error.
   • Go to Help > Show Logs. Scroll through the client log file. Look for lines related to the synchronization attempt. You might see 401 Unauthorized errors or messages indicating login failure. Note the timestamp of the error.

3. Check Server Logs (Server Side):

   • Connect to your server via SSH.
   • Navigate to your project directory: cd ~/joplin-project
   • Check the Joplin Server application logs around the time the error occurred:

     # Show recent logs, maybe increase tail count if needed
     docker-compose logs --tail=100 app
     

   • Look for log entries corresponding to the failed sync attempt (match timestamps if possible). You should see entries indicating a failed login attempt, likely with a 401 status code associated with an API request (e.g., /api/sessions). The log might explicitly state "Unauthorized" or "Invalid credentials".

4. Check Nginx Logs (Server Side):

   • Since the request reached the Joplin application (which returned a 401 error), the Nginx logs should reflect this.
   • Check the Nginx access log:

     sudo tail -n 50 /var/log/nginx/joplin.access.log
     

   • Look for lines corresponding to requests from your client's IP address around the time of the error. You should see requests to /api/... endpoints resulting in a 401 status code. This confirms Nginx forwarded the request, but the application rejected it due to authorization failure.
   • Check the Nginx error log (though it likely won't show anything for a 401 error, as it's an application-level rejection, not an Nginx error):

     sudo tail -n 50 /var/log/nginx/joplin.error.log
     

5. Identify the Cause and Fix:

   • Based on the client error ("Unauthorized"), the client logs (401 error), the Joplin Server logs (401, invalid credentials), and the Nginx logs (showing 401 responses), the clear cause is incorrect login credentials being used by the client.
   • Go back to the Joplin client: Tools > Options > Synchronization.
   • Enter the correct password for your user account.
   • Click "Check synchronization configuration" - it should now succeed.
   • Click "Apply" / "OK".
   • Trigger a manual sync - it should now complete successfully.

Congratulations! You have practiced updating Joplin Server and used a systematic approach involving client and server logs to diagnose and resolve a common synchronization problem.

Conclusion Next Steps

You have successfully navigated the process of self-hosting Joplin Server, progressing from a basic setup to a secured, robust, and maintainable instance. By deploying with Docker, securing communications with Nginx and Let's Encrypt HTTPS, implementing automated backups, and learning basic monitoring and troubleshooting techniques, you've built your own private synchronization backend for your notes.

Key Takeaways:

• Control and Privacy: Self-hosting gives you ultimate control over your note synchronization environment and ensures your data stays private under your management.
• Importance of Security: Using a reverse proxy (Nginx) and HTTPS (Let's Encrypt) is not optional but essential for protecting your data in transit.
• Data Safety: Automated, regular, and tested backups (especially database dumps) are critical insurance against data loss.
• Containerization Benefits: Docker and Docker Compose significantly simplify the deployment, management, and updating of Joplin Server and its dependencies.
• Maintenance is Ongoing: Keep your server OS, Docker, Nginx, Certbot, and Joplin Server itself updated. Regularly check logs and test backups.

Further Exploration:

• Advanced Monitoring: Explore tools like Uptime Kuma for user-friendly uptime monitoring or Prometheus + Grafana for in-depth metrics collection and visualization.
• Offsite Backups: Implement a strategy to copy your backups to a remote location (cloud storage, another server) using tools like rclone or rsync.
• Joplin Client Customization: Dive into userchrome.css and userstyle.css to personalize the look and feel of your Joplin client application.
• Explore Joplin Plugins: Enhance your note-taking workflow by exploring the wide range of plugins available for the Joplin client.
• Alternative Reverse Proxies: Investigate Traefik or Caddy as alternatives to Nginx, especially if you plan to host multiple containerized services.
• Security Hardening: Research further security measures like firewall configuration (ufw), intrusion detection systems (Fail2ban), and Docker security best practices.

Self-hosting is a rewarding journey that offers significant learning opportunities alongside the practical benefits of controlling your own services. By applying the knowledge gained here and continuing to explore, you can confidently manage your Joplin Server and potentially other self-hosted applications, empowering you with valuable technical skills and true data ownership.