VPS Tutorials
Obsidian LiveSync on VPS: CouchDB, Encryption and Backups (2026)
Configure LiveSync with CouchDB, CORS, HTTPS, encryption, multi-device setup, conflicts and backups. Correct the original $120/year two-vault estimate using actual official plan entitlements.

Self-hosted LiveSync connects Obsidian devices through CouchDB, letting you choose where the server and note data reside. It also makes you responsible for credentials, certificates, upgrades, conflicts and recovery. Choose it for control and suitable workloads, rather than assuming it always saves money.
The original incorrectly treated official Sync as universally billed per vault and described unlimited history. The official plan documentation, checked on 2026-11-16, lists Standard with 1 synced vault, 1 GB storage, 5 MB files and 1 month of history; Plus has 10 vaults, 10–100 GB depending on purchased storage, 200 MB files and 12 months of history. Storage is shared across the account. Verify current pricing and entitlement instead of multiplying a monthly fee by every vault.
| Option | Cost basis | Synchronization | Encryption/history | Mobile and maintenance |
|---|---|---|---|---|
| Official Sync | Subscription | Managed synchronization | E2EE and plan-specific retention | Native mobile; provider manages service |
| Self-hosted LiveSync | Plugin plus VPS/time | Incremental near-real-time | Optional E2EE; history depends on plugin/database retention | Desktop/mobile; you maintain CouchDB |
| Remotely Save | Plugin plus supported remote storage | Scheduled/manual | Check plugin encryption and remote/version settings | Mobile support varies with backend |
| Syncthing | Software plus infrastructure | File synchronization | Transport encryption; not equivalent to encrypted remote content; optional versioning | No official iOS client |
| Git plugin | Repository plus tooling | Commit/pull/push workflow | Git history; encrypt separately if needed | Mobile workflow and conflicts require care |
Remotely Save is not continuous LiveSync replication; edits between synchronization runs can conflict. Check its current encryption and retention instead of assuming they depend only on the cloud drive. Syncthing works well for compatible devices, with a separate iOS-client decision. All methods need backups.
LiveSync is especially useful when:
- You have several vaults or larger collections.
- Attachments exceed a managed plan's practical allowance.
- You want to choose the hosting location and administration.
- A maintained VPS already has spare capacity.
For one small text-only vault, managed Sync may be worth the reduced maintenance.
| Starting configuration | Planning assessment |
|---|---|
| 1 vCPU/512 MB | Tight; simultaneous synchronization can exhaust memory |
| 1 vCPU/1 GB | Possible for a small personal deployment; measure |
| 1 vCPU/2 GB | More useful starting headroom |
| 2 vCPU/2 GB+ | Consider for more devices, attachments or shared workloads |
The original's 200–300 MB idle-memory estimate is not a guarantee. Reserve roughly 3–5 times vault size initially, and monitor revisions, chunks, logs and compaction space. A 200 MB vault growing toward 1 GB is a planning example, not an assured growth rate. Start around 20 GB disk where appropriate.
Test latency from your devices; language does not determine their location. Budget VPS options include a $3/month comparison threshold, not guaranteed current inventory or sufficient performance. Consider jurisdiction and access controls even with E2EE: metadata and traffic patterns can remain visible.
mkdir -p ~/obsidian-sync/{data,local.d}
cd ~/obsidian-sync
Create docker-compose.yml, replacing the password with a private random value and choosing a maintained, reviewed CouchDB image:
services:
couchdb:
image: couchdb:3.4
container_name: obsidian-couchdb
restart: unless-stopped
user: "5984:5984"
environment:
- COUCHDB_USER=admin
- COUCHDB_PASSWORD=换成一个长随机密码
volumes:
- ./data:/opt/couchdb/data
- ./local.d:/opt/couchdb/etc/local.d
ports:
- "127.0.0.1:5984:5984"
user: "5984:5984" aligns the container user with its files. Confirm the selected image uses UID 5984 and give data and configuration directories the intended ownership:
sudo chown -R 5984:5984 data local.d
Restrict configuration-file permissions. Bind to 127.0.0.1, and proxy access rather than exposing database port 5984 directly. Docker-published ports need actual binding/network checks, not only a UFW rule.
Use local.d/livesync.ini under local.d/ instead of editing local.ini inside a disposable container:
[couchdb]
single_node = true
max_document_size = 50000000
[chttpd]
require_valid_user = true
max_http_request_size = 4294967296
enable_cors = true
[chttpd_auth]
require_valid_user = true
authentication_redirect = /_utils/session.html
[httpd]
WWW-Authenticate = Basic realm="couchdb"
bind_address = 0.0.0.0
enable_cors = true
[cors]
origins = app://obsidian.md, capacitor://localhost, http://localhost
credentials = true
headers = accept, authorization, content-type, origin, referer
methods = GET,PUT,POST,HEAD,DELETE
max_age = 3600
single_node = trueselects the demonstrated single-node setup.enable_cors = trueand[cors]support browser-origin requests where required.originsincludesapp://obsidian.mdandcapacitor://localhostfor the shown desktop/mobile clients; restrict origins to those actually used.max_http_request_sizein the example allows HTTP requests up to 4 GB. This is not a universal requirement or a 4 GB document limit: max_document_size is separately set to 50,000,000 bytes. Match limits to plugin chunking, memory and proxy limits rather than allowing enormous requests unnecessarily.require_valid_user = truerequires authentication. Also set database membership/security; a password alone does not establish least privilege.
docker compose up -d
docker compose logs -f
Inspect logs and reach Fauxton at http://127.0.0.1:5984/_utils/ through a private SSH tunnel. Use the administrator for setup; evaluate a dedicated database user for routine synchronization once the plugin's setup checks are complete.
Mobile and desktop clients should use a valid, trusted certificate. Avoid relying on untrusted self-signed certificates or disabling certificate verification. With correctly pointed DNS and reachable certificate challenges, Caddy can provide HTTPS:
couchdb.example.com {
encode gzip
reverse_proxy 127.0.0.1:5984
}
Check Host and X-Forwarded-* handling, particularly behind another proxy. Let CouchDB manage the required CORS headers, avoiding duplicate proxy headers. With Nginx, configure proxy_pass and disable proxy_buffering where continuous replication needs streaming; also review timeouts and body limits. See Caddy configuration.
Install Self-hosted LiveSync from the community-plugin catalog, reviewing its trust and supported version. Use its setup wizard, whose wording can vary by version:
| Setting | Value |
|---|---|
| URI | https://couchdb.example.com, without public port 5984 |
| Username/password | Authorized CouchDB account |
| Database | A distinct name such as obsidian-vault for this vault |
Run Test database connection, then Check and fix where the plugin requires setup permissions. Recheck security afterward.
Copy the entire local vault to an independent backup before selecting synchronization direction.
- A genuinely empty new server: populate it from the intended complete local vault.
- An existing authoritative server: populate a new empty device from that server.
Do not overwrite a device that has unsynchronized edits. Inspect the actual warning and test with disposable notes first; choosing the wrong source can propagate empty or stale data.
With correctly configured E2EE, clients encrypt supported note data before upload. Enable Path Obfuscation where appropriate to reduce filename exposure. This does not protect compromised clients or eliminate all server metadata.
Store the data passphrase securely: losing it can make server ciphertext unusable. The vault encryption passphrase and the Setup URI passphrase protect different things; retain both in a password manager and an appropriate recovery process.
A Setup URI beginning with obsidian://setuplivesync?settings= contains sensitive connection settings. On the configured device:
Self-hosted LiveSync: Copy settings as a new Setup URI
Choose a separate protection passphrase. On the new device, select I am adding a device to an existing synchronisation setup and import the URI/passphrase privately. Treat both as credentials; do not post them publicly or send both through the same exposed channel.
An empty new vault can download server data. If a local copy already exists, back it up and reconcile changes before approving any overwrite.
Offline edits to the same note can conflict. The plugin may merge compatible edits; inspect unresolved alternatives in its conflict interface and choose deliberately. Test recovery with the installed version rather than assuming every revision can be retrieved forever.
CouchDB revisions are replication/concurrency mechanisms, not an unlimited archival guarantee. Compaction and plugin retention can remove historical bodies. Synchronization also propagates deletion to other devices, so version history cannot replace an independent backup.
Keep independent vault exports and use the approach in backup guidance. For a small single-node service, a stopped-data backup avoids copying a changing database:
cd ~/obsidian-sync
docker compose stop couchdb
sudo tar czf ~/couchdb-backup-$(date +%F).tar.gz data local.d
docker compose start couchdb
Retain Compose configuration and secrets privately as well as data/local.d, transfer the archive off the VPS, and test restoration in isolation. Check tar success before considering the backup complete, and ensure the service is restarted after failures. Replication to a second CouchDB can remain online, but it can replicate unwanted deletions too; retain independent historical snapshots.
Failed to fetch/CORS: inspect [cors], allowed origins including app://obsidian.md, credentials and TLS. Avoid duplicate CORS headers in the proxy.
Connected but no progress: check proxy_buffering off for Nginx, continuous-request timeouts and proxy/CDN upload limits. Cloudflare can terminate long requests under its actual plan limits.
Desktop works, mobile fails: inspect certificate trust/chain with curl -v https://couchdb.example.com, expiry and DNS; mobile client restrictions can differ.
Database grows: monitor disk and plan compaction with available temporary space:
curl -u admin:密码 -X POST https://couchdb.example.com/obsidian-vault/_compact \
-H "Content-Type: application/json"
Use plugin Auto Compaction if supported, with deliberate retention policy. Compaction can remove old revision bodies; do not run it expecting permanent history. Handle attachment history using supported plugin procedures.
Domain/certificate changes: update the URI and retest synchronization after restarting the client.
Lost encryption passphrase: recover a complete readable copy from a remaining device or independent backup and establish a new setup. Do not assume the server can decrypt it for you.
The original used $5/month for a VPS, $30–50/year for a 1 vCPU/2 GB server, $5–10/month for Sync, and $48–96/year under annual billing. Its $120–240/year two-vault calculation assumed per-vault billing and is not a valid general comparison with the documented Plus entitlement. These are historical budget examples, not current offers.
Count hosting, backup storage, bandwidth and maintenance time. Spare VPS capacity can reduce additional cash cost, while a dedicated purchase solely for one vault may offer little saving. Data location and operational control are the stronger reasons to self-host.