DPTCloud
Back to articles
Technology Insight

Self-Hosting a Private Obsidian Sync Server: A Step-by-Step Guide Using CouchDB and Docker on a VPS

June 4, 2026

Introduction: The Case for Self-Hosting Obsidian Sync

In the modern digital workspace, knowledge management has become a critical asset for professionals, researchers, and entrepreneurs. Obsidian has emerged as a premier tool for building a personal knowledge base, thanks to its local-first philosophy and powerful Markdown-based architecture. However, when it comes to synchronizing notes across multiple devices—such as a desktop, laptop, and mobile device—users often face a dilemma between convenience and complete data privacy.

While Obsidian offers a premium native sync service, many enterprise users and privacy advocates prefer absolute control over their infrastructure. Self-hosting your synchronization backend ensures that your intellectual property, proprietary strategies, and personal notes remain strictly within your perimeter. In this technical guide, we will explore how to architect and deploy a private Obsidian Sync server using Apache CouchDB containerized within Docker on a Virtual Private Server (VPS).

Why CouchDB and Docker?

To achieve real-time, conflict-free synchronization similar to Obsidian's official offering, the community relies heavily on the Obsidian LiveSync plugin. This plugin utilizes the CouchDB replication protocol. CouchDB is a NoSQL database focused on ease of use and a web-scalable architecture. It uses JSON to store data, JavaScript as its query language using MapReduce, and HTTP for an API.

Deploying CouchDB via Docker offers several distinct advantages for system administrators and tech-savvy professionals:

  • Isolation: Docker containers encapsulate the database and its dependencies, preventing conflicts with other applications running on your VPS.
  • Portability: A containerized setup can be easily backed up, migrated, or replicated across different cloud providers with minimal configuration changes.
  • Maintainability: Updating CouchDB involves pulling a new Docker image, drastically simplifying long-term server maintenance.
---

Prerequisites and Environment Setup

Before proceeding with the deployment, ensure your infrastructure meets the following baseline requirements:

  1. A Linux VPS: A modest instance (e.g., 1 vCPU, 1GB–2GB RAM) from providers like DigitalOcean, Linode, or AWS is sufficient for personal or small team use. Ubuntu 22.04 LTS or 24.04 LTS is highly recommended.
  2. A Fully Qualified Domain Name (FQDN): A domain name (e.g., sync.yourdomain.com) pointing to your VPS IP address via an A record. This is essential for implementing SSL encryption.
  3. Docker and Docker Compose: Ensure the latest stable versions of Docker Engine and the Compose plugin are installed on your host machine.
Security Warning: Synchronizing data over unencrypted HTTP exposes your database credentials and sensitive notes to potential interception. Implementing a reverse proxy with an SSL certificate (such as Let's Encrypt) is mandatory for production environments.
---

Step 1: Configuring Docker Compose for CouchDB

To manage our services cleanly, we will utilize Docker Compose. This allows us to define the CouchDB service, network topologies, and persistent storage volumes in a single YAML configuration file. First, connect to your VPS via SSH and create a dedicated project directory:

mkdir -p ~/obsidian-sync && cd ~/obsidian-sync

Next, create a docker-compose.yml file using your preferred text editor and input the following configuration:

version: '3.8'

services:
  couchdb:
    image: couchdb:3.3.3
    container_name: obsidian_couchdb
    restart: always
    environment:
      - COUCHDB_USER=admin
      - COUCHDB_PASSWORD=YourSecurePasswordHere
    volumes:
      - ./data:/opt/couchdb/data
      - ./local.ini:/opt/couchdb/etc/local.ini
    ports:
      - "127.0.0.1:5984:5984"
    networks:
      - sync_network

networks:
  sync_network:
    driver: bridge

Note: We bind the port to 127.0.0.1:5984 deliberately. This prevents the database from being exposed directly to the public internet, forcing all incoming traffic to route safely through our reverse proxy.

---

Step 2: Optimizing CouchDB Settings for Obsidian

Obsidian LiveSync handles a high volume of small requests and structural modifications. To prevent CouchDB from hitting default payload limits and to ensure smooth performance, we must adjust the database configurations via a local.ini file in our project directory:

[chttpd]
max_http_request_size = 4294967296
require_valid_user = true

[couchdb]
single_node = true
max_dbs_open = 500

[httpd]
WWW-Authenticate = Basic realm="couchdb"

This configuration designates CouchDB to run efficiently as a single-node setup, enforces user authentication for all endpoints, and increases the maximum HTTP request size to accommodate larger binary attachments (such as embedded PDFs or high-resolution images) within your vault.

---

Step 3: Deploying and Securing the Stack

With the configuration files properly populated, launch your container in detached mode:

docker compose up -d

Verify that the container is executing correctly by checking the logs:

docker compose logs -f couchdb

Implementing Nginx and Let's Encrypt SSL

To bridge public HTTPS requests to our internal CouchDB container, install Nginx and Certbot on your host server:

sudo apt update
sudo apt install nginx certbot python3-certbot-nginx -y

Create an Nginx server block configuration at /etc/nginx/sites-available/obsidian-sync:

server {
    listen 80;
    server_name sync.yourdomain.com;

    location / {
        proxy_pass [http://127.0.0.1:5984](http://127.0.0.1:5984);
        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_buffering off;
    }
}

Enable the site configuration, test Nginx for syntax compliance, and reload the daemon:

sudo ln -s /etc/nginx/sites-available/obsidian-sync /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Finally, provision a trusted SSL certificate from Let's Encrypt to ensure your traffic is fully encrypted:

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

Step 4: Creating the Database via Fauxton UI

CouchDB features a built-in web dashboard named Fauxton. You can now access it securely by navigating to [https://sync.yourdomain.com/_utils/](https://sync.yourdomain.com/_utils/) in your browser. Log in using the COUCHDB_USER and COUCHDB_PASSWORD credentials established in your Docker Compose file.

Once authenticated, perform the following steps:

  1. Navigate to the Databases tab on the left sidebar.
  2. Click the Create Database button in the upper right corner.
  3. Name the database obsidian-vault (or a preference of your choice).
  4. Ensure Non-partitioned is selected and confirm creation.
---

Step 5: Configuring Obsidian LiveSync Plugin

With your enterprise-grade backend operational, you can now link your client devices. Open Obsidian and complete the initialization steps on your primary machine:

Installing the Plugin

  1. Navigate to Settings > Community Plugins.
  2. Turn on community plugins if disabled, click Browse, and search for Self-hosted LiveSync.
  3. Install and enable the plugin.

Configuring Connection Profiles

Open the plugin settings and input your server details precisely:

  • URI: [https://sync.yourdomain.com](https://sync.yourdomain.com)
  • Username: Your configured CouchDB administrator name.
  • Password: Your secure administrator password.
  • Database Name: obsidian-vault

Under the security parameters, enable End-to-End Encryption (E2EE). Choose a strong, memorable encryption password. This ensures that even though you own the server, data stored within CouchDB is encrypted at rest and unreadable to anyone accessing the database directly without your key.

Click Test Connection. Once validation succeeds, initiate your first synchronization. To link secondary devices (such as an Android or iOS phone), simply install the plugin on the mobile device and import your configuration via the generated setup URI or QR code within the plugin settings.

---

Conclusion: Maintenance and Peace of Mind

By executing this deployment, you have successfully freed your knowledge management stack from commercial data silos. Your personal database is now securely stored on your dedicated cloud infrastructure, synchronizing reliably across your ecosystem in real-time. To maintain operational stability, ensure you schedule automated cron-job backups of the ~/obsidian-sync/data directory to a separate cold-storage location regularly.

With absolute data sovereignty achieved, you can confidently utilize Obsidian as your ultimate repository for ideas, proprietary systems, and strategic planning.

Self-Hosting a Private Obsidian Sync Server: A Step-by-Step Guide Using CouchDB and Docker on a VPS | DPTCloud