obsidi-backup

obsidi-backup

A lightweight sidecar container that automatically backs up your Obsidian vault with git versioning and cloud storage via restic.

Why?

Obsidian Sync is great, but it's not a backup. This container provides:

• Git history - Every change tracked, browse history, diff versions
• Cloud backup - Encrypted, deduplicated backups to Azure, S3, B2, or any restic backend
• AI commit messages - Optional Claude-powered summaries of what changed
• Notifications - Know when backups succeed or fail

Features

• File watching - Real-time monitoring with configurable debounce
• Git versioning - Auto-commits with AI-generated or timestamp messages
• Cloud backup - Restic to Azure, S3, B2, SFTP, or local storage
• Health endpoint - HTTP /health for monitoring and orchestration
• Configurable retention - Customize daily, weekly, monthly snapshots
• Notifications - Discord, Slack, or generic webhooks
• Dry run mode - Test configuration without making changes
• Multi-arch - Runs on amd64 and arm64 (Raspberry Pi, Apple Silicon)

Quick Start

services:
  vault-backup:
    image: ghcr.io/cameronsjo/obsidi-backup:latest
    environment:
      TZ: America/Chicago
      # Storage backend (Azure example)
      AZURE_ACCOUNT_NAME: mystorageaccount
      AZURE_ACCOUNT_KEY: ${AZURE_ACCOUNT_KEY}
      RESTIC_REPOSITORY: azure:obsidian-backup:/vault
      RESTIC_PASSWORD: ${RESTIC_PASSWORD}
      # Optional: AI commit messages
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
      # Optional: Notifications
      DISCORD_WEBHOOK_URL: ${DISCORD_WEBHOOK_URL}
    volumes:
      - /path/to/your/vault:/vault
    ports:
      - "8080:8080"

After starting, initialize the restic repository:

docker exec vault-backup restic init

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Obsidian Vault Backup                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────┐    ┌──────────┐    ┌────────┐    ┌─────────┐  │
│  │ Watchdog│───▶│ Debounce │───▶│  Git   │───▶│ Restic  │  │
│  │ Monitor │    │ (5 min)  │    │ Commit │    │ Backup  │  │
│  └─────────┘    └──────────┘    └────────┘    └─────────┘  │
│       │                              │             │        │
│       │                              ▼             │        │
│       │                        ┌──────────┐       │        │
│       │                        │   LLM    │       │        │
│       │                        │ (Haiku)  │       │        │
│       │                        └──────────┘       │        │
│       │                                           ▼        │
│       │         ┌──────────┐              ┌───────────┐    │
│       └────────▶│  Health  │              │  Notify   │    │
│                 │  Server  │              │ (Discord) │    │
│                 └──────────┘              └───────────┘    │
│                      │                                      │
└──────────────────────┼──────────────────────────────────────┘
                       ▼
                  :8080/health

Flow:

1. Watchdog monitors the vault for file changes
2. Debounce waits for 5 minutes of inactivity (configurable)
3. Git commit stages all changes, generates commit message (AI or timestamp)
4. Restic backup encrypts and uploads to cloud storage
5. Prune removes old snapshots per retention policy
6. Notify sends success/failure alerts

Configuration

Storage Backends

Restic supports many backends. Set RESTIC_REPOSITORY accordingly:

Backend	Repository Format	Additional Env Vars
Azure Blob	azure:container:/path	AZURE_ACCOUNT_NAME, AZURE_ACCOUNT_KEY
AWS S3	s3:s3.amazonaws.com/bucket	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
Backblaze B2	b2:bucket:/path	B2_ACCOUNT_ID, B2_ACCOUNT_KEY
SFTP	sftp:user@host:/path	SSH key or RESTIC_PASSWORD
Local	/path/to/backup	-
REST Server	rest:http://host:8000/	-

See restic documentation for all options.

Environment Variables

Required

Variable	Description
RESTIC_REPOSITORY	Restic repository URL
RESTIC_PASSWORD	Restic encryption password