Skip to main content

VPS Migration & Disaster Recovery Runbook

This guide covers the end-to-end procedure for performing automated encrypted backups and restoring the entire Sleeper Service environment onto a clean Ubuntu 24.04 VPS instance.

1. Automated Encrypted Backup Pipeline​

Off-site backups are packaged as compressed tarballs and encrypted using AES-256-CBC with PBKDF2 key derivation before transmission via SFTP/FTPS.

Backup Scope​

The archive encapsulates:

  • ~/.hermes/ (Configuration, state databases, session logs, skills, persistent memory, and cron job definitions)
  • ~/.garminconnect/ (OAuth session tokens)
  • ~/sleeper-health/ (Health application codebase)
  • ~/sleeper-docs/ (Docusaurus documentation source)
  • All operational scripts (*.py, *.ics, *.env)

2. Decryption & Restoration Guide​

If the primary VPS fails or you are provisioning a new instance:

Step 1: Base System Setup​

On the new clean Ubuntu 24.04 server:

# Update package lists and install essentials
sudo apt update && sudo apt install -y curl git ufw jq unzip openssl python3-venv python3-pip

# Install & join Tailscale mesh
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

# Install Hermes Agent runtime
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Step 2: Download & Decrypt the Backup​

Retrieve the latest encrypted archive from the off-site storage (sleeper_dr_backup_YYYYMMDD.tar.gz.enc):

# Run openssl to decrypt the archive
openssl enc -d -aes-256-cbc -pbkdf2 -iter 100000 \
  -in sleeper_dr_backup_YYYYMMDD.tar.gz.enc \
  -out sleeper_dr_backup_decrypted.tar.gz

Decryption Passphrase:

jcnlkK_8jqxxzMgdVS45o0nQX5OfuZPYArTdCRq6X1E

Step 3: Extract Archive to Filesystem​

Extract the archive into the ubuntu home directory:

tar -xzvf sleeper_dr_backup_decrypted.tar.gz -C /

Step 4: Python Virtual Environment & Dependencies​

Restore the active Python virtual environment:

python3 -m venv /home/ubuntu/.venv
/home/ubuntu/.venv/bin/pip install --upgrade pip
/home/ubuntu/.venv/bin/pip install requests supabase garminconnect icalendar paramiko

Step 5: Verification & Service Startup​

Run system checks and start the Hermes background daemon:

# Run Hermes health check
hermes doctor

# Start background gateway service & schedulers
hermes gateway start

# Verify cron jobs are scheduled
hermes cron list

3. Manual On-Demand Backup Command​

To manually generate an encrypted backup on the local machine:

# 1. Package archive
tar -czvf /tmp/sleeper_backup.tar.gz \
  /home/ubuntu/.hermes \
  /home/ubuntu/.garminconnect \
  /home/ubuntu/sleeper-health \
  /home/ubuntu/sleeper-docs \
  /home/ubuntu/*.py \
  /home/ubuntu/*.ics

# 2. Encrypt with AES-256-CBC
openssl enc -aes-256-cbc -pbkdf2 -iter 100000 \
  -in /tmp/sleeper_backup.tar.gz \
  -out /tmp/sleeper_dr_backup_$(date +%Y%m%d).tar.gz.enc \
  -k "jcnlkK_8jqxxzMgdVS45o0nQX5OfuZPYArTdCRq6X1E"

# 3. Clean up plaintext temp archive
rm /tmp/sleeper_backup.tar.gz