Self-Hosted Vault Sync

Sync your Obsidian vault with a self‑hosted server instance, with offline queue, conflict handling and progress feedback.

This plugin is designed to meet the community plugin requirements described in the official Obsidian help (https://publish.obsidian.md/help-ru/Продвинутое+использование/Сторонние+плагины) and follows the structure and build workflow of the official sample plugin (https://github.com/obsidianmd/obsidian-sample-plugin).

---

Features

• Self‑hosted sync: Connect a vault to your own Obsidian Server instance using a secure connection string, without any third‑party cloud.
• Two‑way synchronization: Upload local changes and pull remote updates for your markdown files.
• Attachment / resource sync (optional): Sync images and other non‑markdown resources when enabled in settings.
• Sync on save: Automatically sync the current file whenever you save it.
• Automatic background sync: Periodic sync on a customizable interval while Obsidian is open.
• Status bar indicator: See current sync status (idle, syncing, error, offline, conflicts) and last sync time in the status bar.
• Offline queue: When you are offline, changes are queued and automatically sent once the connection is restored.
• Conflict detection & resolution: Detects server conflicts and prompts you to resolve them, so you never silently lose data.
• Progress modal for large syncs: For large vaults, a modal progress bar shows scan/upload progress.
• Device registration & heartbeats: Registers the current device on the server and periodically sends heartbeats to keep the device online.
• In‑app plugin updates from server: Optionally download updated main.js and manifest.json for this plugin directly from your Obsidian Server, with permission checks.

---

Requirements

• Obsidian: minAppVersion 0.15.0 or newer (as declared in manifest.json).
• Obsidian Server: A running instance of this repository's backend/web UI, configured with at least one vault.
• Network access: The device running Obsidian must be able to reach your Obsidian Server URL (LAN, VPN or public HTTPS).

The plugin does not require an Obsidian account and does not talk to any external services other than your own server.

---

Installation

From Obsidian Community Plugins (recommended once published)

1. Open Settings → Community plugins.
2. Make sure Restricted mode is disabled.
3. Click Browse, search for “Obsidian Server Sync”.
4. Open the plugin page, click Install, then Enable.

Manual installation (from Git / release .zip)

1. Download main.js, manifest.json (and styles.css if present) from a release of this repository.

2. Create a folder inside your vault:

   <your-vault>/.obsidian/plugins/obsidian-server-sync/
   

3. Copy the files into that folder so the structure looks like:

   .obsidian/plugins/obsidian-server-sync/
   ├── main.js
   ├── manifest.json
   └── styles.css (optional)
   

4. Restart Obsidian or reload plugins.

5. Go to Settings → Community plugins and enable Obsidian Server Sync.

Development setup

This folder is a standard Obsidian plugin project modeled after the official sample plugin.

cd obsidian-plugin
npm install
npm run dev     # watch / development build
npm run build   # production build

The compiled main.js and manifest.json are emitted in this folder and can be copied to your vault’s .obsidian/plugins/obsidian-server-sync/ directory for local testing.

---

Connecting to your Obsidian Server

The plugin uses a connection string generated by the server’s Web UI to configure:

• server URL
• vault ID
• device / access token
• optional flags such as “sync resources”

Typical flow:

1. Open the Web UI of your Obsidian Server.
2. Navigate to the section where the server shows a QR code / connection string for a specific vault (see the server documentation in this repo).
3. On the device where Obsidian is running:
   • Either copy the connection string from the Web UI to the clipboard.
   • Or scan the QR code with the device and copy the decoded string.
4. In Obsidian, open Settings → Community plugins → Obsidian Server Sync.
5. If you are not yet connected, you will see a “Connection String / QR” block:
   • Paste the connection string into the text field, or
   • Click “Scan QR / Paste from Clipboard” to read from the system clipboard (desktop and supported mobile platforms).
6. The plugin validates the string, saves the server URL, vault ID and token, and immediately:
   • Sends an initial heartbeat to register/promote your device token.
   • Starts the first full sync of the vault.

Once connected, the settings tab shows the Server URL and Vault ID as read‑only, plus a “Disconnect” button that clears the connection and stops auto sync.

---

Usage

• Manual sync

  • Use the command palette and run “Obsidian Server Sync: Sync now”, or
  • Click the ribbon icon with the refresh symbol.
  • A notice at the bottom of the window shows sync progress and result.

• Automatic sync

  • Enable “Sync on save” in plugin settings to sync the current file whenever it is saved.
  • Enable “Auto sync” to periodically sync the vault.
  • Use “Sync interval” slider to control how often background sync runs.

• Status bar

  • The status bar shows an icon and short text for the current state:
    • ◈ Idle
    • ⟳ Syncing…
    • ✓ Last: …
    • ⊘ Offline (…)
    • ⚠ Conflicts
    • ✗ Error
  • Click the status bar item to see a detailed status notice (network, last sync, queue size, conflicts).

• Offline queue

  • If your device is offline, modified files are queued instead of failing.
  • When the connection is restored, batched operations are replayed automatically.
  • You can inspect and clear the queue from the plugin settings.

• Conflict resolution

  • When the server detects diverging versions, the plugin increments the conflict count and surfaces it in notices and the status bar.
  • A conflict resolver UI helps you decide which version to keep (local vs remote), so you can resolve issues early.

• Big vaults

  • For sync operations involving many files, a dedicated sync progress modal appears, with a progress bar and per‑phase messages (scanning, uploading, done).

• In‑app plugin updates

  • The settings tab shows the current plugin version and can check against your server’s latest published version.
  • If a newer version is available, you can download updated main.js and manifest.json directly into the plugin folder (subject to file system permissions).

---

Configuration options (overview)

All options are available under Settings → Community plugins → Obsidian Server Sync:

• Connection String / QR
  • First‑time setup: paste or read a connection string from the server’s Web UI.
• Server URL (read‑only after connection)
• Vault ID (read‑only after connection)
• Connection
  • Disconnect button to clear connection and stop auto sync.
• Sync on save
  • Toggle syncing the current note whenever it is saved.
• Sync non‑markdown files
  • Toggle syncing attachments and other resources.
• Auto sync
  • Enable/disable periodic background sync.
• Sync interval
  • Slider in minutes for auto sync cadence.
• Sync now
  • Button to manually trigger a sync.
• Update check interval
  • Slider that controls how often sync is allowed to check for plugin updates on the server (0 disables update checks).
• Status
  • Show current online/offline state and offline queue size, with actions to show status and clear the queue.

---

Privacy & security

• All data is sent only to the server URL defined by your connection string.
• The plugin does not collect analytics and does not phone home to any third‑party service.
• Device tokens are managed entirely by your own Obsidian Server.
• When the plugin cannot write to your vault’s plugin folder (e.g. filesystem permissions), it falls back to safe behavior and asks you to update manually.

---

Troubleshooting

• Plugin does not appear in the list

  • Check that the folder is named obsidian-server-sync and placed in <vault>/.obsidian/plugins/.
  • Ensure manifest.json and main.js are present.
  • Restart Obsidian.

• Cannot connect / sync fails immediately

  • Verify the Obsidian Server Web UI is reachable from this device.
  • Make sure you pasted the full connection string, without extra spaces.
  • If you regenerated the connection string on the server, apply the new one in plugin settings.

• Offline errors

  • If you see “offline” status, the plugin automatically queues operations.
  • Once the connection is back, run “Sync now” or wait for auto sync to flush the queue.

• Permission errors on plugin update

  • On some systems, Obsidian may not be allowed to write into its own plugin directory.
  • In that case, download the updated files from your Obsidian Server manually and replace main.js / manifest.json in the plugin folder.

For more installation and setup details, see docs/plugin-setup.md in this repository.

---

Versioning & releases

This plugin uses a versions.json file (as recommended in the official sample plugin) to map plugin versions to minimum supported Obsidian versions. When publishing a new version:

1. Bump the version in manifest.json and package.json.
2. Add or update the entry in versions.json.
3. Build the plugin (npm run build).
4. Create a GitHub release and upload manifest.json, main.js (and styles.css if present).

---

License

The plugin code is licensed under the same license as the main project (see the repository‑level LICENSE file).

---

Краткое описание по‑русски

Obsidian Server Sync — это плагин для синхронизации хранилища Obsidian с вашим собственным (self‑hosted) сервером Obsidian Server.

• Поддержка markdown‑файлов и вложений (при включённой опции).
• Автосинхронизация по таймеру и синхронизация при сохранении.
• Очередь офлайн‑операций: изменения не пропадают, пока вы без интернета.
• Разрешение конфликтов и индикатор статуса в строке состояния.
• Подключение через строку подключения / QR‑код, который выдаёт Web‑интерфейс сервера.

Для подробной инструкции по установке и настройке см. раздел docs/plugin-setup.md и описание выше.