Documentation / Litestream

Litestream — Next Steps & External Setup

Everything you need to do outside the codebase to enable Litestream SQLite replication.

1. Rails Credentials

Run bin/rails credentials:edit and add:

litestream:
  replica_bucket: "your-litestream-bucket"    # Dedicated R2 bucket for DB backups
  replica_key_id: "your-r2-access-key-id"     # Can reuse Cloudflare R2 keys
  replica_access_key: "your-r2-secret-key"    # Can reuse Cloudflare R2 keys
  r2_account_id: "your-cloudflare-account-id" # Can reuse Cloudflare account ID
  dashboard_username: "admin"
  dashboard_password: "a-secure-dashboard-password"

Note: Litestream credentials can share the same R2 access keys as Cloudflare storage. The initializer falls back to cloudflare credentials if litestream-specific keys aren't set. However, using a dedicated bucket is recommended to separate file uploads from DB replicas.

2. Create a Dedicated R2 Bucket

  1. Go to Cloudflare Dashboard → R2 Object Storage
  2. Click Create bucket
  3. Name: yourapp-litestream (keep it separate from your file uploads bucket)
  4. Location: choose a region close to your server
  5. No public access needed — Litestream only needs API access

3. API Credentials

You can either:

  • Reuse the same R2 API token created for Cloudflare R2 file storage
  • Create a dedicated token scoped only to the litestream bucket for better security

If creating a dedicated token:

  1. Go to R2 → Manage R2 API Tokens → Create API Token
  2. Name: yourapp-litestream
  3. Permissions: Object Read & Write
  4. Specify bucket: Select your litestream bucket only
  5. Copy the Access Key ID and Secret Access Key

4. Verification

  1. Check replication is running: After deploying, look for Litestream log messages in Puma output: 
    litestream: replicating storage/production.sqlite3
litestream: replicating storage/production_cache.sqlite3
...
  2. Check R2 bucket: In Cloudflare Dashboard → R2 → your litestream bucket → you should see replica files appearing
  3. Visit the dashboard: Navigate to /litestream as an admin user → see replication status for all 4 databases
  4. Test restore: (on a non-production copy) 
    bin/rails litestream:restore -- --database storage/production.sqlite3

5. Restore in Disaster Recovery

To restore from a backup:

# List available generations (snapshots)
bin/rails litestream:generations -- --database storage/production.sqlite3

# Restore latest snapshot
bin/rails litestream:restore -- --database storage/production.sqlite3

# Restore to a specific point in time
bin/rails litestream:restore -- --database storage/production.sqlite3 --timestamp 2025-01-15T00:00:00Z

# Restore all 4 databases
for db in production production_cache production_queue production_cable; do
  bin/rails litestream:restore -- --database storage/${db}.sqlite3
done

6. Deployment Checklist

  • Dedicated R2 bucket created for DB replicas (yourapp-litestream)
  • Litestream credentials added to Rails credentials
  • LITESTREAM_IN_PUMA: true in config/deploy.yml
  • After deploy: check Puma logs for Litestream replication messages
  • R2 bucket shows replica files for all 4 databases
  • Visit /litestream as admin → dashboard loads and shows replication status
  • Test restore on a non-production copy