homelab/compose/services/backrest/README.md

Backrest - Web UI for Restic Backups

Backrest provides a modern web interface for managing Restic backups with support for Backblaze B2 (S3-compatible) storage.

Features

• Web UI: User-friendly interface for managing backups
• Encrypted Backups: Uses Restic for encrypted, deduplicated backups
• Scheduling: Built-in scheduler for automatic backups
• Monitoring: View backup status, logs, and statistics
• Multiple Repositories: Support for multiple backup destinations
• Retention Policies: Automatic cleanup of old backups
• Notifications: Email and webhook notifications for backup events

Quick Start

1. Start the Service

cd compose/services/backrest
docker compose up -d

2. Access Web UI

Open your browser and navigate to:

• https://backup.fig.systems
• Or: https://backup.edfig.dev

Login with your SSO credentials (tinyauth).

3. Configure Backblaze B2 Repository

1. Create B2 Bucket (if not already done):

   • Go to https://secure.backblaze.com/b2_buckets.htm
   • Click "Create a Bucket"
   • Name: homelab-backups (or your choice)
   • Files: Private
   • Encryption: Server-Side (or Disabled - Backrest encrypts client-side)

2. Create Application Key:

   • Go to https://secure.backblaze.com/app_keys.htm
   • Click "Add a New Application Key"
   • Name: backrest-homelab
   • Access: Read and Write
   • Bucket: Select your backup bucket
   • Save the keyID and applicationKey

3. Add Repository in Backrest:

   • Click "Add Repository"
   • Repository Name: B2 Immich Photos
   • Storage Type: S3-compatible storage
   • Configuration:

     Endpoint: s3.us-west-002.backblazeb2.com
     Region: us-west-002
     Bucket: homelab-backups
     Path: /immich-photos
     Access Key ID: [your B2 keyID]
     Secret Access Key: [your B2 applicationKey]
     

   • Encryption Password: Set a strong password (SAVE THIS!)
   • Click "Initialize Repository"

4. Create Backup Plan

1. Add Plan:

   • Click "Add Plan"
   • Plan Name: Immich Daily Backup
   • Repository: Select your B2 repository
   • Paths to Backup:
     • /backups/immich
   • Exclude Patterns (optional):
     • *.tmp
     • *.log

2. Schedule:

   • Backup Schedule: 0 3 * * * (3 AM daily)
   • Enable "Automatic Backups"

3. Retention Policy:

   • Keep Last: 7 daily backups
   • Keep Weekly: 4 weekly backups
   • Keep Monthly: 6 monthly backups
   • Keep Yearly: 2 yearly backups

4. Notifications (optional):

   • Configure email or webhook for backup status
   • Alert on failures

5. Run First Backup

Click "Run Now" to start your first backup immediately.

Backup Locations

The service has access to these directories:

• /backups/immich - Immich photos (read-only)
• /backups/homelab-config - All compose configurations (read-only)

You can add more volumes in compose.yaml as needed.

Monitoring

View Backup Status

In the Backrest web UI:

• Dashboard shows all backup plans and their status
• Click on a plan to see backup history
• View logs for detailed information

Check Repository Size

# Via web UI: Repository → Statistics
# Shows: Total size, deduplicated size, number of snapshots

Verify Backups

Backrest has built-in verification:

1. Go to Repository → Verify
2. Click "Run Verification"
3. Check results for any errors

Restore Files

Via Web UI

1. Go to Plan → Snapshots
2. Select snapshot to restore
3. Click "Browse Files"
4. Select files/folders to restore
5. Choose restore location
6. Click "Restore"

Via CLI (Advanced)

# List snapshots
docker exec backrest restic -r [repository] snapshots

# Restore specific snapshot
docker exec backrest restic -r [repository] restore [snapshot-id] --target /restore

# Restore specific file
docker exec backrest restic -r [repository] restore [snapshot-id] --target /restore --include /path/to/file

Configuration Backup

Backup Backrest Config

Your Backrest configuration (plans, schedules, repositories) is stored in:

• ./config/config.json

Important: Backup this file! It contains your repository credentials (encrypted).

# Create backup
cp config/config.json config/config.json.backup

# Restore backup
cp config/config.json.backup config/config.json
docker compose restart

Export Configuration

In Web UI:

1. Settings → Export Configuration
2. Save JSON file securely
3. Store encryption passwords separately

Troubleshooting

Cannot Access Web UI

Check container status:

docker compose logs backrest
docker compose ps

Verify Traefik routing:

docker logs traefik | grep backrest

Backup Fails

1. Check Logs:

   • Web UI: Plan → View Logs
   • Or: docker compose logs -f backrest

2. Verify B2 Credentials:

   • Test connection in Repository settings
   • Ensure application key has read/write access

3. Check Disk Space:

   df -h
   docker exec backrest df -h /cache
   

Repository Locked

If a backup is interrupted, the repository may be locked:

# Via Web UI: Repository → Unlock
# Or via CLI:
docker exec backrest restic -r [repository] unlock

Slow Backups

1. Enable Caching: Already configured via XDG_CACHE_HOME
2. Increase Upload Speed: Check B2 endpoint is geographically close
3. Exclude Unnecessary Files: Add patterns to exclude list

Security Considerations

Encryption

• Client-side: All data encrypted before upload
• Repository Password: Required to access backups
• Storage: Store repository passwords in password manager

Access Control

• SSO Protected: Web UI requires authentication via tinyauth
• API Keys: B2 application keys scoped to specific bucket
• Read-Only Mounts: Backup sources mounted read-only

Best Practices

1. Test Restores: Regularly test restoring files
2. Monitor Backups: Check backup status weekly
3. Verify Integrity: Run verification monthly
4. Secure Passwords: Use strong, unique repository passwords
5. Document Recovery: Keep recovery procedures documented
6. Offsite Storage: B2 provides geographic redundancy

Advanced Configuration

Add More Backup Sources

Edit compose.yaml to add more volumes:

volumes:
  - /path/to/backup:/backups/name:ro

Then create a new backup plan in the web UI.

Multiple Repositories

Configure multiple destinations:

1. Primary: Backblaze B2
2. Secondary: Local NAS/USB drive
3. Archive: Another cloud provider

Webhooks

Configure webhooks for monitoring:

1. Settings → Notifications
2. Add Webhook URL (e.g., Discord, Slack, Uptime Kuma)
3. Select events: Backup Success, Backup Failure

Custom Retention

Fine-tune retention policies:

--keep-within 7d
--keep-within-daily 30d
--keep-within-weekly 90d
--keep-within-monthly 1y
--keep-within-yearly 5y

Resource Usage

Typical Usage:

• CPU: Low (spikes during backup)
• Memory: ~200-500MB
• Disk: Cache grows over time (monitor)
• Network: Depends on backup size

Monitoring Cache Size:

du -sh compose/services/backrest/cache

Clean cache if needed (safe to delete - will rebuild):

rm -rf compose/services/backrest/cache/*
docker compose restart

Backrest vs Duplicati

We chose Backrest over Duplicati because:

• Modern: Built on Restic (actively developed)
• Performance: Better deduplication and compression
• Reliability: Restic is battle-tested
• Features: More advanced scheduling and monitoring
• UI: Clean, responsive interface

Cost Estimation

Backblaze B2 Pricing (2024):

• Storage: $0.006/GB/month
• Download: $0.01/GB (first 3x storage free)
• Upload: Free

Example: 100GB Immich photos

• Storage Cost: $0.60/month
• Download (3 restores/month): Free
• Total: ~$0.60/month

With Deduplication:

• First backup: 100GB
• Daily incrementals: ~1-5GB
• Monthly growth: ~20GB
• Avg monthly cost: ~$0.70

Resources

• Backrest Documentation
• Restic Documentation
• Backblaze B2 Documentation
• S3-compatible API Guide

Next Steps

1. ✅ Configure B2 repository
2. ✅ Create backup plan for Immich
3. ⬜ Run initial backup
4. ⬜ Verify backup integrity
5. ⬜ Test restore procedure
6. ⬜ Set up notifications
7. ⬜ Add homelab-config backups
8. ⬜ Schedule monthly verification