Obsidian Sync

💡 Quick Navigation

🎯 Why I Self-Host Sync

🧱 Overall Architecture

🗄️ CouchDB and LiveSync

🖥️ Obsidian Client Container

🌐 Quartz Publishing Boundary

💬 Artalk Comments

💾 Backup and Restore

⚠️ Operations and Boundaries

Home Lab Overview

This Obsidian Sync setup is not the official Obsidian Sync service. It uses Self-hosted LiveSync + CouchDB to synchronize my Obsidian vault. The same compose stack also runs Quartz publishing and Artalk comments, so it becomes one workflow for writing, syncing, publishing, and comments.

The core rule is: sync data and public publishing must be treated separately. CouchDB and the full vault are private sync data. Quartz only reads the public subtrees explicitly placed under host and host_en.

Important

This is a public note, so it does not publish CouchDB credentials, LiveSync URLs, vault IDs, plugin settings, sync tokens, .env contents, internal IPs, domains, Artalk config, comment databases, or backup archive contents.

🎯 Why I Self-Host Sync

Notes are long-term data, not just app settings

My Obsidian vault is not just a folder of documents. It is a long-term knowledge base, Home Lab documentation, publishing drafts, and operation notes. Keeping it on one device is risky; depending entirely on an external sync service reduces control.

Self-hosting sync lets me:

sync the same vault across devices
keep control of the data
connect the synced public content to Quartz publishing
protect the vault and sync database with my own backup strategy

Sync and publishing are different things

Sync is about keeping my own devices up to date. Publishing is about turning only public content into a website.

That boundary matters. The most dangerous failure is not sync breaking; it is accidentally publishing content that should have stayed private.

🧱 Overall Architecture

flowchart TD
    DEV[Obsidian Devices] --> LS[Self-hosted LiveSync]
    LS --> CDB[CouchDB<br/>obsidian-livesync]
    OC[Obsidian Client<br/>container] --> CDB
    OC --> VAULT[(Obsidian Vault)]

    VAULT --> CH[host<br/>Chinese public subtree]
    VAULT --> EN[host_en<br/>English public subtree]
    CH --> QZCN[Quartz Chinese Site]
    EN --> QZEN[Quartz English Site]
    QZCN --> NPM[Nginx Proxy Manager]
    QZEN --> NPM
    QZCN --> ART[Artalk Comments]

Stack summary

Component	Container	Image	Role
CouchDB	`obsidian-livesync`	`couchdb:latest`	LiveSync backend database
Obsidian Client	`obsidian-client`	`linuxserver/obsidian:latest`	Containerized Obsidian client / Web UI
Quartz Chinese site	`obsidian-quartz`	`ghcr.io/jackyzha0/quartz:latest`	Publishes the `host` public subtree
Quartz English site	`obsidian-quartz-en`	`ghcr.io/jackyzha0/quartz:latest`	Publishes the `host_en` public subtree
Artalk	`obsidian-artalk`	`artalk/artalk-go:latest`	Comment system for Quartz

Note

Most images in this stack currently use latest. This is convenient for quick updates, but weaker for reproducible restores. A more stable long-term approach is to pin version tags and record pre/post-upgrade checks.

🗄️ CouchDB and LiveSync

CouchDB is the backend for Self-hosted LiveSync. Obsidian devices sync through the LiveSync plugin, and CouchDB stores the database state needed for synchronization.

Data I protect

CouchDB data volume
CouchDB config volume
private LiveSync plugin settings
the vault itself

Data I do not publish

CouchDB admin username or password
CouchDB hashes, salts, cookies, UUIDs
.couch database files
LiveSync URL
vault ID
plugin data.json
sync passwords, tokens, or keys

LiveSync logs are also not safe to publish directly because they can reveal vault IDs, sync state, timestamps, and device behavior patterns.

🖥️ Obsidian Client Container

This stack also runs a containerized Obsidian client. Its job is to keep an Obsidian environment available on the server side and expose a browser-accessible UI.

Container role

Item	Notes
Image	`linuxserver/obsidian:latest`
Dependency	Starts after CouchDB
Config	Obsidian app/plugin settings
Vault	Mounts the full Obsidian vault
UI	Browser-accessible, but the real entry point is not published here

Obsidian client config, browser cache, local storage, and plugin data can all contain private information. They should not be included in public notes or public backup details.

🌐 Quartz Publishing Boundary

Quartz runs in the same compose stack as the sync service, but the data boundary is different.

Full Obsidian Vault
├── host      -> Chinese Quartz site
├── host_en   -> English Quartz site
├── WIP       -> private, not published
├── .trash    -> private, not published
└── .obsidian -> private, not published

The Quartz containers mount only public subtrees as read-only content:

Chinese site reads host
English site reads host_en

This lets me maintain drafts, private notes, and public articles in the same vault while only exposing content that has been intentionally moved into a publish subtree.

Pre-publish checks

Do not link to WIP/services or other private notes
Do not reference .trash or old logs
Do not include real domains, IPs, credentials, or tokens
Use \| for aliased wikilinks inside Markdown tables so the table parser does not split the link
Attach only images that are confirmed safe to publish

💬 Artalk Comments

Artalk also runs in this stack to provide comments for Quartz posts. It is not part of Obsidian sync itself, but in this deployment it is part of the publishing workflow.

Artalk needs its own backup coverage:

config
database
logs
uploaded images

Public notes should not include Artalk raw config, comment database contents, commenter information, emails, IPs, tokens, captcha settings, or OAuth details.

💾 Backup and Restore

The Obsidian sync stack cannot be backed up by looking only at the vault folder. The sync database, Obsidian client config, Quartz customization, and comment system all need separate consideration.

Backup categories

Category	Reason
Vault	Original Markdown, attachments, public notes, and private notes
CouchDB data/config	LiveSync state and backend database
Obsidian config	plugins, theme, workspace, and client settings
Compose / `.env`	startup method, volume mapping, and environment variables
Quartz config/components/styles	site customization; generated public output can be rebuilt, but customizations should not be lost
Artalk data	comments, config, uploaded images

Restore order concept

Restore compose and volume mapping
Restore CouchDB data/config
Restore Obsidian vault and client config
Start CouchDB, then the Obsidian client
Confirm LiveSync does not create a large conflict set
Start Quartz and confirm host / host_en publishing works
Start Artalk and confirm comments load correctly

Warning

Restoring only the vault but not CouchDB state can make sync clients see stale state or create conflicts. Restoring CouchDB without the vault can also leave devices and server state inconsistent. They should be verified together.

⚠️ Operations Principles and Security Boundaries

Private data matters more than publishing convenience

The easiest serious mistake is not a failed service start. It is accidentally publishing private content. That is why public content is kept in host and host_en instead of letting Quartz scan the whole vault.

Do not publish raw config

CouchDB, LiveSync plugin, Obsidian client, Quartz, Artalk, and NPM configs may all contain sensitive information. Public notes should describe architecture and operations principles, not raw config files.

Upgrade conservatively

Both the sync layer and publishing layer affect daily use. Before upgrading, I confirm backups. After upgrading, I check:

Obsidian devices can sync
CouchDB responds normally
Obsidian client can open the vault
Quartz Chinese / English sites regenerate
Artalk comments still load
NPM / Authelia entry paths still work

Conclusion

This Obsidian Sync stack is more than note synchronization. It connects my personal knowledge base, public blog, bilingual publishing, and comment system into one workflow.

The important part is the boundary: CouchDB / LiveSync / the full vault are private sync data; Quartz reads only intentionally public subtrees; NPM and Authelia handle entry; backups must protect sync data, publishing customization, and comment data together.

Further reading: Home Lab Overview, Nginx Proxy Manager, Authelia

Luke's Tech Notes

Explorer

Obsidian Sync

Obsidian Sync

🎯 Why I Self-Host Sync

Notes are long-term data, not just app settings

Sync and publishing are different things

🧱 Overall Architecture

Stack summary

🗄️ CouchDB and LiveSync

Data I protect

Data I do not publish

🖥️ Obsidian Client Container

Container role

🌐 Quartz Publishing Boundary

Pre-publish checks

💬 Artalk Comments

💾 Backup and Restore

Backup categories

Restore order concept

⚠️ Operations Principles and Security Boundaries

Private data matters more than publishing convenience

Do not publish raw config

Upgrade conservatively

Conclusion

Graph View

Table of Contents

Backlinks