A self-hosted sync solution for Obsidian using CouchDB and Tailscale. Securely sync your notes across all your devices through your private Tailscale network.
- Self-hosted sync — Full control over your data with CouchDB
- Secure networking — Access your sync server securely via Tailscale VPN
- Docker-based — Easy deployment with Docker Compose
- Backup & Restore — Built-in scripts for data management
- Auto-initialization — Database setup happens automatically on first run
- Docker & Docker Compose
- Tailscale account with an auth key
- Obsidian with the Self-hosted LiveSync plugin
git clone https://github.com/skritik-dev/obsidian-sync.git
cd obsidian-synccp .env.example .envEdit .env with your credentials:
# CouchDB Credentials
COUCHDB_USER=admin
COUCHDB_PASSWORD=your_secure_password
COUCHDB_DB_NAME=obsidian
# Tailscale Configuration
# Generate at: https://login.tailscale.com/admin/settings/keys
# Enable `Reusable` or `Ephemeral` tags
TS_AUTHKEY=tskey-auth-xxxxx
TS_HOSTNAME=obsidian-serverdocker compose up -d- Go to settings -> Community plugins -> Install the Self-hosted LiveSync plugin in Obsidian
- Open LiveSync plugin settings and configure:
- Search for Active remote configuration
- Select CouchDB
- Add TailScale connection url
- Add CouchDB credentials
- Add CouchDB database name
- Search for Active remote configuration
- Copy the Setup URI
- Paste this setup URI to your other devices with you want to connect
Note:
Make sure your all your devices are connected to Tailscale to access the sync server. Change the sync setting in the Self-hosted LiveSync plugin to LiveSync
Instead of exposing ports locally, the couchdb container networks directly through the tailscale container. This ensures your data never leaves your private mesh network.
obsidian-sync/
└── .git
├── docker-compose.yml # Main orchestration file
├── .env.example # Environment template
├── couchdb/
│ ├── Dockerfile # Custom CouchDB image
│ └── local.ini # CouchDB configuration
├── scripts/
│ ├── backup.sh # Database backup script
│ └── restore.sh # Database restore script
└── backups/ # Backup storage directory
└── .gitignore
└── README.md
./scripts/backup.shBackups are saved to ./backups/ with timestamps.
./scripts/restore.sh ./backups/obsidian_backup_2026-01-18_12-00-00.tar.gzWARNING! Restoring will overwrite your current database. Make sure to backup first!
Custom CouchDB image (couchdb/local.ini) is pre-configured for Obsidian LiveSync:
| Setting | Value | Description |
|---|---|---|
max_document_size |
200MB | Large vault support |
max_http_request_size |
4GB | Large file uploads |
enable_cors |
true | Cross-origin requests |
require_valid_user |
true | Authentication required |
| Variable | Description |
|---|---|
TS_AUTHKEY |
Authentication key from Tailscale admin console |
TS_HOSTNAME |
Device name on your Tailnet |
# Check container logs
docker compose logs -f
# Verify Tailscale connection
docker exec obsidian-tailscale tailscale status- Ensure your device is on Tailscale
- Verify the hostname:
ping obsidian-server - Check CouchDB is healthy:
curl http://obsidian-server:5984
Go to LiveSync plugins setting and set Use Request API to avoid CORS problem as true.
- Check Key Expiry: Tailscale Auth Keys expire every 90 days by default. Go to the Tailscale Admin Console. Disable key expiry.
- Verify VPN State: Ensure the Tailscale app is Active (Connected) on both your Docker host and your client device (Phone/Laptop).
- Check Network Identity: Ensure you are logged into the same Tailscale account on all devices.
docker compose down -v
docker compose up -dContributions are welcome! Please feel free to submit a Pull Request.