obsidian-livesync-fs

A headless sync daemon and automation pipeline that continuously synchronizes an Obsidian Self-hosted LiveSync vault (stored in CouchDB) down to the local filesystem.

---

🗺️ Project Roadmap

Phase	Description	Status	Tracking Issue
(1) Initial Release	Continuous filesystem sync from CouchDB via systemd with LiveSync Setup URI configuration	Active (Current)	#1
(2) Git Auto-Commit	Batched git auto-commit & push (debounced up to 1 commit/min with catch-up guarantee)	Planned	#2
(3) LLM RAG Engine	Retrieval-Augmented Generation pipeline & vector/FTS database for querying notes	Planned	#3
(4) Read-Only Webpage	Read-only web viewer for notes without requiring the Obsidian client	Planned	#4

---

📦 Initial Release: Filesystem Sync via Systemd

The initial release provides a systemd daemon that connects to your CouchDB LiveSync backend using your Obsidian LiveSync Setup URI, initializes the local replication state, and keeps your markdown files and attachments mirrored to a local directory in real time.

How Systemd is Configured to Include the LiveSync URI

The LiveSync Setup URI (obsidian://setuplivesync?settings=...) encapsulates CouchDB connection strings, credentials, and E2EE encryption passphrases. It is sensitive data and must not be exposed in command line arguments.

We provide two production-grade patterns:

1. Dedicated Environment File (EnvironmentFile=):
   • Stored with 0600 permissions at /etc/obsidian-livesync/livesync.env (system) or ~/.config/obsidian-livesync/livesync.env (user).
   • Injected into the runner process safely.
2. systemd Isolated Credentials (LoadCredential=):
   • Modern systemd (v250+) feature that mounts credentials in a private memory-backed filesystem at $CREDENTIALS_DIRECTORY/setup_uri.
   • Supports TPM2 encryption at rest using systemd-creds.

Detailed architectural documentation is available in docs/systemd-configuration.md.

---

🚀 Quick Start

Option A: User Service (systemctl --user)

Best for single-user workstations where notes reside in your home folder.

1. Install files for current user:

   ./scripts/install.sh user
   

2. Configure your LiveSync Setup URI: Edit ~/.config/obsidian-livesync/livesync.env:

   LIVESYNC_SETUP_URI="obsidian://setuplivesync?settings=YOUR_SETUP_URI"
   VAULT_PATH="${HOME}/obsidian-vault"
   

3. Enable and start the service:

   systemctl --user enable --now obsidian-livesync.service
   

4. Verify status:

   systemctl --user status obsidian-livesync.service
   journalctl --user -u obsidian-livesync.service -f
   

5. (Optional) Keep syncing while logged out:

   loginctl enable-linger "${USER}"
   

---

Option B: System Service (systemctl)

Best for headless servers or shared infrastructure.

1. Install as root:

   sudo ./scripts/install.sh system
   

2. Configure /etc/obsidian-livesync/livesync.env:

   sudo nano /etc/obsidian-livesync/livesync.env
   

3. Enable and start:

   sudo systemctl enable --now obsidian-livesync.service
   sudo journalctl -u obsidian-livesync.service -f
   

---

🛠️ Repository Structure

• bin/obsidian-livesync-runner: Main runner script that manages initialization, pre-sync, and continuous daemon execution.
• config/livesync.env.example: Configuration template for Setup URI and paths.
• systemd/obsidian-livesync.service: System-wide systemd service definition.
• systemd/obsidian-livesync-user.service: User-level systemd service definition.
• scripts/install.sh: Installer script for user or system services.
• scripts/show-setup-qr.sh: Displays the ASCII/Unicode QR code in terminal for mobile device onboarding.
• scripts/create_roadmap_issues.sh: Script to automatically create roadmap issues on Forgejo (git.sepio.pl).
• docs/systemd-configuration.md: In-depth guide on systemd URI and secret handling.