yams/docs/operations/backup.md

YAMS Backup & Recovery (Operations)

A guide to back up and restore YAMS safely. Copy/paste first, refine later.

TL;DR

• What to back up:
  • Data root: $YAMS_STORAGE (contains yams.db and storage/)
  • Config: ~/.config/yams (or your XDG_CONFIG_HOME/yams)
• Hot (online) backup (SQLite-safe + files):

  # Set locations
  export YAMS_STORAGE="${YAMS_STORAGE:-$HOME/.local/share/yams}"
  export BKP_DIR="/var/backups/yams/$(date +%F)"
  
  # 1) Backup SQLite DB atomically
  mkdir -p "$BKP_DIR"
  sqlite3 "$YAMS_STORAGE/yams.db" ".backup '$BKP_DIR/yams.db'"
  
  # 2) Sync content store files
  rsync -a --delete "$YAMS_STORAGE/storage/" "$BKP_DIR/storage/"
  
  # (Optional) Config backup
  rsync -a --delete "${XDG_CONFIG_HOME:-$HOME/.config}/yams/" "$BKP_DIR/config/"
  

• Cold (offline) backup (max safety):

  sudo systemctl stop yams
  rsync -a --delete "$YAMS_STORAGE/" "/var/backups/yams/$(date +%F)/"
  sudo systemctl start yams
  

• Restore:

  sudo systemctl stop yams
  export YAMS_STORAGE="${YAMS_STORAGE:-/var/lib/yams}"
  export BKP_DIR="/var/backups/yams/2025-08-11"
  
  # Restore DB and storage
  rsync -a --delete "$BKP_DIR/storage/" "$YAMS_STORAGE/storage/"
  install -d "$(dirname "$YAMS_STORAGE/yams.db")"
  cp -f "$BKP_DIR/yams.db" "$YAMS_STORAGE/yams.db"
  
  # Restore config (if backed up)
  rsync -a --delete "$BKP_DIR/config/" "${XDG_CONFIG_HOME:-/etc}/yams/"
  
  # Fix ownership/permissions
  sudo chown -R yams:yams "$YAMS_STORAGE" "${XDG_CONFIG_HOME:-/etc}/yams"
  sudo chmod 600 "${XDG_CONFIG_HOME:-/etc}/yams/keys/ed25519.pem" 2>/dev/null || true
  
  sudo systemctl start yams
  yams stats
  

---

What to back up (and why)

• $YAMS_STORAGE
  • yams.db (SQLite metadata & search indices)
  • storage/ (content-addressed files/chunks)
• Config (XDG config dir)
  • ${XDG_CONFIG_HOME:-$HOME/.config}/yams/
  • Includes keys under keys/ (private key should be 0600)
• Optional: logs, operational scripts, deployment/unit files

Rule of thumb: If you restore yams.db, storage/, and the config/keys, you’re back.

---

Backup strategies

Choose one:

1. Online (no downtime)

• Use sqlite3 .backup for a transactionally consistent DB snapshot
• rsync the storage/ directory
• For very high write rates, consider running rsync twice to reduce window of changed files

2. Offline (brief downtime, simpler)

• Stop service → rsync entire $YAMS_STORAGE/ → start service

3. Filesystem snapshots (advanced)

• Use ZFS/Btrfs/LVM snapshots for consistent point-in-time images
• Ensure snapshot includes both DB and storage/

---

Online (hot) backup – practical script