andras/vault-link
1
0
Fork 0
Code Issues Pull requests 18 Projects Releases 55 Packages Wiki Activity Actions 1

Simplify docs

Browse source
This commit is contained in:
Andras Schmelczer 2025-11-22 12:37:21 +00:00
parent 00d2061627
commit a1a4610109
9 changed files with 162 additions and 325 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/architecture/data-flow.md
View file

@ -1,6 +1,6 @@
# Data Flow # Data Flow
This document provides a detailed look at how data flows through the VaultLink system, from client to server and back. How data flows through VaultLink, from client to server and back.
## Connection Lifecycle ## Connection Lifecycle

36
docs/architecture/index.md
View file

@ -1,6 +1,6 @@
# Architecture Overview # Architecture Overview
VaultLink is built as a distributed system with a central sync server and multiple clients. This document explains the high-level architecture and design decisions. Central sync server with multiple clients. High-level architecture and design decisions.
## System Components ## System Components
@ -40,7 +40,7 @@ VaultLink is built as a distributed system with a central sync server and multip
### Sync Server ### Sync Server
The central authority for synchronization, written in Rust using Axum framework. Central authority for synchronization. Rust + Axum framework.
**Responsibilities**: **Responsibilities**:
@ -61,7 +61,7 @@ The central authority for synchronization, written in Rust using Axum framework.
### Sync Client Library ### Sync Client Library
TypeScript library providing core synchronization logic, used by both the Obsidian plugin and CLI client. TypeScript library with core sync logic. Used by Obsidian plugin and CLI client.
**Responsibilities**: **Responsibilities**:
@ -310,35 +310,13 @@ Token-based authentication on connection:
## Technology Choices ## Technology Choices
### Why Rust for Server? **Rust**: Low latency, memory safe, excellent async with Tokio, compile-time SQL verification
- **Performance**: Low latency for real-time sync **SQLite**: No separate database server, fast for reads, single file per vault, backups are file copies
- **Memory safety**: No crashes from memory bugs
- **Concurrency**: Excellent async support with Tokio
- **Type safety**: Catch bugs at compile time
- **SQLx**: Compile-time SQL verification
### Why SQLite? **WebSocket**: Bidirectional push, no polling overhead, built-in browser/Node.js support
- **Simplicity**: No separate database server required **Operational Transformation**: Automatic conflict resolution, preserves all edits, real-time collaboration
- **Performance**: Fast for read-heavy workloads
- **Reliability**: Battle-tested, ACID compliant
- **Portability**: Single file per vault
- **Backups**: Simple file copy
### Why WebSocket?
- **Real-time**: Bidirectional push for instant updates
- **Efficiency**: Persistent connection, no polling overhead
- **Simplicity**: Built-in browser/Node.js support
- **Standards**: Well-supported protocol
### Why Operational Transformation?
- **Automatic conflict resolution**: No manual merging required
- **Preserves intent**: All edits are kept
- **Real-time collaboration**: Users see changes as they happen
- **Proven algorithm**: Used by Google Docs, etc.
## Design Principles ## Design Principles

2
docs/architecture/sync-algorithm.md
View file

@ -1,6 +1,6 @@
# Sync Algorithm # Sync Algorithm
VaultLink uses operational transformation (OT) to handle concurrent edits and maintain consistency across clients. This document explains how the algorithm works. VaultLink uses operational transformation (OT) to handle concurrent edits and maintain consistency across clients.
## Operational Transformation ## Operational Transformation

2
docs/guide/cli-client.md
View file

@ -1,6 +1,6 @@
# CLI Client # CLI Client
The VaultLink CLI client provides standalone synchronization without requiring Obsidian. Perfect for servers, automation, backups, or syncing vaults on headless systems. Sync vaults without Obsidian. Works on servers, automation, backups, headless systems.
## Installation ## Installation

190
docs/guide/getting-started.md
View file

@ -1,48 +1,45 @@
# Getting Started # Getting Started
This guide will walk you through setting up VaultLink from scratch. You'll have a working sync server and connected client in under 10 minutes. Set up VaultLink in 5 minutes. Deploy server, connect clients, done.
## Prerequisites ## Prerequisites
- Docker installed (recommended) or Rust toolchain for building from source - Docker (or Rust toolchain if building from source)
- Basic familiarity with command line - A server (VPS, home server, or localhost for testing)
- A server or machine to host the sync server (can be localhost for testing)
## Quick Start ## Step 1: Deploy Server
### Step 1: Deploy the Sync Server Create `config.yml`:
The fastest way to get started is with Docker: ```yaml
database:
databases_directory_path: databases
max_connections_per_vault: 12
cursor_timeout_seconds: 60
server:
host: 0.0.0.0
port: 3000
max_body_size_mb: 512
max_clients_per_vault: 256
response_timeout_seconds: 60
users:
user_configs:
- name: admin
token: change-this-to-secure-random-token
vault_access:
type: allow_access_to_all
logging:
log_directory: logs
log_rotation: 7days
```
::: tip
Generate secure token: `openssl rand -hex 32`
:::
Run server:
```bash ```bash
# Create a directory for server data
mkdir -p ~/vaultlink-data
cd ~/vaultlink-data
# Create a basic configuration file
cat > config.yml << 'EOF'
database:
databases_directory_path: databases
max_connections_per_vault: 12
cursor_timeout_seconds: 60
server:
host: 0.0.0.0
port: 3000
max_body_size_mb: 512
max_clients_per_vault: 256
response_timeout_seconds: 60
users:
user_configs:
- name: admin
token: change-this-to-a-secure-random-token
vault_access:
type: allow_access_to_all
logging:
log_directory: logs
log_rotation: 7days
EOF
# Run the server
docker run -d \ docker run -d \
--name vaultlink-server \ --name vaultlink-server \
--restart unless-stopped \ --restart unless-stopped \
@ -52,136 +49,75 @@ docker run -d \
/app/sync_server /data/config.yml /app/sync_server /data/config.yml
``` ```
::: warning Verify: `curl http://localhost:3000/vaults/test/ping` should return `pong`
Change the token in `config.yml` to a secure random value before deploying to production!
:::
Verify the server is running: ## Step 2: Connect Client
```bash ### Obsidian Plugin
curl http://localhost:3000/vaults/test/ping
```
You should see: `pong` 1. Settings → Community Plugins → Browse
2. Search "VaultLink", install, enable
3. Configure:
- Server URL: `ws://localhost:3000` (or `wss://your-server.com` for SSL)
- Token: Your token from config.yml
- Vault Name: `default`
### Step 2: Choose Your Client [Full plugin guide →](/guide/obsidian-plugin)
You can connect to VaultLink using either the Obsidian plugin or the standalone CLI client. ### CLI Client
#### Option A: Obsidian Plugin
1. Open Obsidian Settings → Community Plugins
2. Browse community plugins and search for "VaultLink"
3. Install and enable the plugin
4. Configure the plugin:
- **Server URL**: `ws://localhost:3000` (or your server address)
- **Token**: The token from your `config.yml`
- **Vault Name**: `default` (or any name you choose)
[Read the full Obsidian plugin guide →](/guide/obsidian-plugin)
#### Option B: CLI Client
Perfect for syncing vaults without Obsidian:
```bash ```bash
docker run -d \ docker run -d \
--name vaultlink-cli \ --name vaultlink-cli \
--restart unless-stopped \ --restart unless-stopped \
-v /path/to/your/vault:/vault \ -v /path/to/vault:/vault \
ghcr.io/schmelczer/vault-link-cli:latest \ ghcr.io/schmelczer/vault-link-cli:latest \
-l /vault \ -l /vault -r ws://localhost:3000 -t your-token -v default
-r ws://localhost:3000 \
-t change-this-to-a-secure-random-token \
-v default
``` ```
Replace `/path/to/your/vault` with the directory containing your files. [Full CLI guide →](/guide/cli-client)
[Read the full CLI client guide →](/guide/cli-client) ## Production Setup
## Next Steps For production:
### Production Deployment 1. **SSL/TLS**: Use Nginx/Caddy reverse proxy for `wss://` ([setup guide](/guide/server-setup#ssl-tls-with-reverse-proxy))
2. **Secure tokens**: Generate with `openssl rand -hex 32`, don't reuse the example
3. **Firewall**: Only expose port 3000 to reverse proxy
4. **Backups**: SQLite databases are in `databases/` directory
For production use, you should: ## Multiple Users
1. **Use HTTPS/WSS**: Put the sync server behind a reverse proxy with SSL
2. **Secure tokens**: Generate cryptographically random tokens
3. **Configure backups**: Back up the SQLite databases regularly
4. **Set up monitoring**: Use Docker health checks and logging
[Learn about production deployment →](/guide/server-setup#production-deployment)
### Multiple Users
To add more users or restrict vault access:
```yaml ```yaml
users: users:
user_configs: user_configs:
- name: alice - name: alice
token: alice-secure-token token: alice-token
vault_access: vault_access:
type: allow_list type: allow_list
allowed: allowed:
- personal - personal
- shared - shared
- name: bob - name: bob
token: bob-secure-token token: bob-token
vault_access: vault_access:
type: allow_list type: allow_list
allowed: allowed:
- shared - shared
``` ```
[Learn about authentication configuration →](/config/authentication) [Auth docs →](/config/authentication)
### Advanced Configuration
Explore advanced server options:
- Database tuning for large vaults
- Rate limiting and connection limits
- Custom logging and log rotation
- Multi-vault setups
[View configuration reference →](/config/server)
## Architecture Overview
Want to understand how VaultLink works under the hood?
[Read the architecture documentation →](/architecture/)
## Troubleshooting ## Troubleshooting
### Server won't start **Server won't start**: `docker logs vaultlink-server`
Check Docker logs: **Client can't connect**:
```bash 1. Verify: `curl http://your-server:3000/vaults/test/ping`
docker logs vaultlink-server 2. Check URL: `ws://` for HTTP, `wss://` for HTTPS
``` 3. Verify token matches config.yml
Common issues: **Files not syncing**: Check client logs, verify vault name matches
- Port 3000 already in use: Change the port mapping `-p 3001:3000` [Server setup →](/guide/server-setup) | [Architecture →](/architecture/)
- Config file errors: Validate YAML syntax
- Permission issues: Ensure the volume mount is writable
### Client can't connect
1. Verify server is accessible: `curl http://your-server:3000/vaults/test/ping`
2. Check WebSocket connectivity (browser dev tools or wscat)
3. Verify token matches between client and server config
4. Check firewall rules allow port 3000
### Files not syncing
1. Check client logs for errors
2. Verify vault name matches on both server and client
3. Ensure user has access to the vault (check server config)
4. Check for file size limits (default 10MB for CLI)
For more help, [open an issue on GitHub](https://github.com/schmelczer/vault-link/issues).

2
docs/guide/obsidian-plugin.md
View file

@ -1,6 +1,6 @@
# Obsidian Plugin # Obsidian Plugin
The VaultLink Obsidian plugin provides native real-time synchronization directly within Obsidian. Real-time sync for Obsidian vaults.
## Installation ## Installation

12
docs/guide/server-setup.md
View file

@ -1,12 +1,12 @@
# Server Setup # Server Setup
This guide covers deploying the VaultLink sync server in various environments, from local development to production infrastructure. Deploy VaultLink server via Docker, binary, or build from source.
## Deployment Options ## Deployment Options
### Docker (Recommended) ### Docker (Recommended)
Docker provides the easiest deployment path with built-in health checks and minimal dependencies. Easiest deployment path, includes health checks.
#### Basic Docker Deployment #### Basic Docker Deployment
@ -60,7 +60,7 @@ docker compose up -d
### Binary Installation ### Binary Installation
Download pre-built binaries from [GitHub Releases](https://github.com/schmelczer/vault-link/releases). Download pre-built binaries from [GitHub Releases](https://github.com/schmelczer/vault-link/releases):
```bash ```bash
# Download the binary for your platform # Download the binary for your platform
@ -75,11 +75,7 @@ chmod +x sync_server-linux-x86_64
### Build from Source ### Build from Source
Requirements: Requirements: Rust 1.89.0+, SQLite development headers, SQLx CLI
- Rust 1.89.0 or later
- SQLite development headers
- SQLx CLI
```bash ```bash
# Clone the repository # Clone the repository

162
docs/guide/what-is-vaultlink.md
View file

@ -1,125 +1,69 @@
# What is VaultLink? # What is VaultLink?
VaultLink is a self-hosted real-time synchronization system for Obsidian vaults. It provides collaborative file syncing with automatic conflict resolution, designed for users who want complete control over their data. Self-hosted sync for Obsidian vaults with automatic conflict-free merging. Edit with any tool, collaborate in real-time, no conflict markers.
## Overview ## The Problem
VaultLink consists of three main components: Syncing Obsidian vaults across devices or sharing with teammates sucks:
### Sync Server - **Commercial services**: Lock-in, subscriptions, third-party access to your data
- **Git**: Manual conflict resolution with `<<<<<<<` markers interrupting your workflow
- **Cloud storage**: Last-write-wins data loss or manual conflict resolution
- **CRDT solutions**: Only work if you edit inside Obsidian (break if you use Vim, VS Code, etc.)
A Rust-based WebSocket server that handles: ## VaultLink's Solution
- Real-time bidirectional synchronization Differential synchronization with operational transformation.
- Document versioning with SQLite
- User authentication and vault access control
- Operational transformation for conflict resolution
### Obsidian Plugin Edit files with Obsidian, Vim, VS Code, or any editor. VaultLink compares versions and automatically merges all changes. No operation tracking required, no conflict markers, no data loss.
A native Obsidian plugin that:
- Integrates sync directly into your Obsidian workflow
- Provides real-time updates as you edit
- Handles file watching and automatic synchronization
- Works across desktop and mobile platforms
### CLI Client
A standalone synchronization client that:
- Syncs vaults without requiring Obsidian
- Perfect for servers, automation, or backup systems
- Provides file watching and bidirectional sync
- Runs in Docker or as a standalone binary
## Key Features
### Real-Time Synchronization
Changes are synchronized immediately via WebSocket connections. When multiple users edit the same file, operational transformation ensures all edits are preserved without conflicts.
### Self-Hosted Architecture
Run the sync server on your own infrastructure:
- Full control over data storage and access
- No dependency on third-party services
- Configurable authentication and authorization
- Deploy anywhere: cloud VPS, home server, or localhost
### Operational Transformation
VaultLink uses the `reconcile-text` library for intelligent conflict resolution:
- Simultaneous edits are automatically merged
- No manual conflict resolution required
- Preserves intent of all contributors
- Works seamlessly in the background
### Flexible Authentication
Configure user access per vault:
- Token-based authentication
- Per-user vault access control
- Allow-list or deny-list patterns
- Support for multiple users and vaults
## Use Cases
### Personal Sync
Synchronize your Obsidian vault across multiple devices:
- Laptop, desktop, and mobile in real-time
- No cloud service subscription required
- Full privacy and data control
### Team Collaboration
Share knowledge bases with teammates:
- Real-time collaborative editing
- Granular access control per vault
- Self-hosted for enterprise security requirements
### Automated Backups
Use the CLI client for automated workflows:
- Scheduled backups to remote servers
- Integration with existing backup systems
- Headless operation without Obsidian
### Development & Testing
Synchronize documentation across environments:
- Keep docs in sync with development environments
- Automated deployment of documentation
- Version control integration
## How It Works ## How It Works
1. **Server Setup**: Deploy the sync server on your infrastructure 1. **Server**: Rust WebSocket server with SQLite stores document versions
2. **Authentication**: Configure users and vault access in `config.yml` 2. **Clients**: Obsidian plugin or CLI client watches filesystem changes
3. **Client Connection**: Connect via Obsidian plugin or CLI client 3. **Sync**: Changes upload to server, server broadcasts to other clients
4. **Initial Sync**: Client uploads local files to server 4. **Merge**: [reconcile-text](https://schmelczer.dev/reconcile) automatically merges concurrent edits
5. **Real-Time Updates**: Changes sync bidirectionally via WebSocket
6. **Conflict Resolution**: Operational transformation handles simultaneous edits
## Technology Stack No CRDT infrastructure. No operation logs. Just file comparison and smart merging.
- **Server**: Rust with Axum framework, SQLite database, WebSocket protocol ## Key Advantages
- **Frontend**: TypeScript with WebSocket client, npm workspaces
- **Sync Algorithm**: reconcile-text operational transformation library **Editor agnostic**: Edit files with any tool. Other solutions break when you edit outside their ecosystem.
- **Deployment**: Docker images, binary releases, or source builds
**Self-hosted**: Your data, your server. No third parties, no subscriptions, no surprises.
**Automatic merging**: Operational transformation handles conflicts without interrupting your workflow.
**Production-ready**: Comprehensive tests, E2E tests, battle-tested. Many alternatives have zero tests.
**Collaborative**: Real-time sync with cursor tracking. See where teammates are editing.
## Not Tied to Obsidian
VaultLink syncs Markdown files. Use it for:
- Obsidian vaults (Obsidian desktop + mobile + CLI)
- Technical documentation (VS Code, your-editor, CLI)
- Academic writing (multiple Markdown editors)
- Automated workflows (CLI client for backups/CI/CD)
The Obsidian plugin is just a convenience wrapper around the sync client.
## Quick Comparison
| Feature | VaultLink | Git | Cloud Sync | CRDT Solutions |
| ------------------- | --------- | --- | ---------- | -------------- |
| Self-hosted | ✅ | ✅ | ❌ | Varies |
| Any editor | ✅ | ✅ | ✅ | ❌ |
| No conflict markers | ✅ | ❌ | ❌ | ✅ |
| Real-time | ✅ | ❌ | ❌ | ✅ |
| No subscriptions | ✅ | ✅ | ❌ | Varies |
| Comprehensive tests | ✅ | N/A | N/A | ❌ |
[Detailed comparison with alternatives →](/guide/alternatives)
## Next Steps ## Next Steps
Ready to get started? - [Get started →](/guide/getting-started) (5 minute setup)
- [See the architecture →](/architecture/) (understand how it works)
- [Getting Started Guide →](/guide/getting-started) - [Compare alternatives →](/guide/alternatives) (why VaultLink vs others)
- [Server Setup →](/guide/server-setup)
- [Architecture Overview →](/architecture/)

79
docs/index.md
View file

@ -3,8 +3,8 @@ layout: home
hero: hero:
name: VaultLink name: VaultLink
text: Self-Hosted Sync for Obsidian text: Self-Hosted Obsidian Sync
tagline: Real-time collaborative file synchronization for your knowledge base tagline: Edit with any tool. Automatic conflict-free merging. Your infrastructure.
image: image:
src: /logo.svg src: /logo.svg
alt: VaultLink alt: VaultLink
@ -13,60 +13,43 @@ hero:
text: Get Started text: Get Started
link: /guide/getting-started link: /guide/getting-started
- theme: alt - theme: alt
text: View on GitHub text: Why VaultLink?
link: https://github.com/schmelczer/vault-link link: /guide/what-is-vaultlink
features: features:
- icon: 🚀 - title: Edit Anywhere
title: Real-Time Synchronization details: Use Obsidian, Vim, VS Code, or any editor. VaultLink syncs files, not keystrokes—edit however you want
details: Operational transformation-based conflict resolution ensures your files stay in sync across devices without data loss - title: Your Data, Your Server
- icon: 🔒 details: Fully self-hosted. No third parties, no subscriptions, no data mining. Single Docker container or binary
title: Self-Hosted & Private - title: No Conflict Markers
details: Run your own sync server. Your data stays on your infrastructure with full control over access and privacy details: Automatic merge using operational transformation. Never see conflict markers in your notes again
- icon: 🎯 - title: Real-Time Collaboration
title: Obsidian Plugin details: See teammate cursors, merge edits instantly. Rust-powered WebSocket server with SQLite
details: Native integration with Obsidian for seamless synchronization directly within your favorite note-taking app - title: Open Source Everything
- icon: 🖥️ details: MIT licensed. Server, clients, and sync algorithm are all open source. No proprietary components
title: CLI Client - title: Battle-Tested
details: Sync vaults to any system using the standalone CLI client. Perfect for servers, automation, or headless setups details: Comprehensive test suite. E2E tests. Used in production. Unlike alternatives with zero tests
- icon: ⚡
title: Built for Performance
details: Rust-powered WebSocket server with SQLite backend delivers blazing-fast sync performance
- icon: 🛠️
title: Flexible Deployment
details: Deploy via Docker, binary releases, or build from source. Configure authentication and access controls to fit your needs
--- ---
## Why Self-Host?
**You own your knowledge base.** Commercial sync services can disappear, change pricing, or lock you out. VaultLink runs on your infrastructure—VPS, home server, or localhost.
**Edit with any tool.** Other solutions require CRDT-aware editors or break when you edit outside Obsidian. VaultLink uses differential sync: edit files however you want, sync handles the rest.
**No conflict markers.** Git forces manual merging. Other tools use last-write-wins. VaultLink's operational transformation automatically merges all changes without data loss or workflow interruption.
[See how VaultLink compares to alternatives →](/guide/alternatives)
## Quick Start ## Quick Start
Deploy the sync server: Deploy server (single command):
```bash ```bash
docker run -d \ docker run -d -p 3000:3000 -v $(pwd)/data:/data \
-p 3000:3000 \ ghcr.io/schmelczer/vault-link-server:latest
-v $(pwd)/data:/data \
ghcr.io/schmelczer/vault-link-server:latest \
/app/sync_server config.yml
``` ```
Install the Obsidian plugin or use the CLI client: Then install the [Obsidian plugin](/guide/obsidian-plugin) or [CLI client](/guide/cli-client).
```bash [Full setup guide →](/guide/getting-started)
docker run -v /path/to/vault:/vault \
ghcr.io/schmelczer/vault-link-cli:latest \
-l /vault -r wss://your-server.com -t your-token -v default
```
[Learn more →](/guide/getting-started)
## Why VaultLink?
VaultLink provides a complete self-hosted synchronization solution for Obsidian:
- **No third-party services**: Your data never leaves your infrastructure
- **Operational transformation**: Smart conflict resolution that preserves all changes
- **Multi-platform**: Works with Obsidian plugin or standalone CLI on any system
- **Production-ready**: Docker images, health checks, and comprehensive logging
- **Open source**: MIT licensed with active development
[Read the architecture overview →](/architecture/)