vaultwarden/BACKUP.md

Vaultwarden Backup and Restore

What Gets Backed Up

Critical (Required for restore):

• PostgreSQL Database - All vault data (passwords, notes, attachments metadata, etc.)
• rsa_key.pem - RSA private key (required to decrypt existing vault data)
• .env file - Database credentials and SMTP configuration

Important:

• config.json - Vaultwarden admin settings

Excluded (regenerated automatically):

• icon_cache/ - Website favicons
• tmp/ - Temporary files

Backup Location

All backups are stored in: /srv/backups/vaultwarden/

Each backup includes:

• vaultwarden_db_YYYYMMDD_HHMMSS.dump - PostgreSQL database (compressed)
• vaultwarden_data_YYYYMMDD_HHMMSS.tar.gz - Data directory (config + RSA key)
• vaultwarden_env_YYYYMMDD_HHMMSS.env - Environment variables

Manual Backup

Run the backup script manually:

/srv/backups/scripts/backup-vaultwarden.sh

Automated Backups

Set up daily automated backups using cron:

# Create log directory
sudo mkdir -p /var/log/vaultwarden
sudo chown pkartch:pkartch /var/log/vaultwarden

# Edit crontab
crontab -e

# Add this line for daily backups at 2:00 AM
0 2 * * * /srv/backups/scripts/backup-vaultwarden.sh >> /var/log/vaultwarden/backup.log 2>&1

Alternative schedules:

# Every 6 hours
0 */6 * * * /srv/backups/scripts/backup-vaultwarden.sh >> /var/log/vaultwarden/backup.log 2>&1

# Twice daily (2 AM and 2 PM)
0 2,14 * * * /srv/backups/scripts/backup-vaultwarden.sh >> /var/log/vaultwarden/backup.log 2>&1

# Weekly on Sunday at 3 AM
0 3 * * 0 /srv/backups/scripts/backup-vaultwarden.sh >> /var/log/vaultwarden/backup.log 2>&1

Restore from Backup

1. List available backups:

/srv/backups/scripts/restore-vaultwarden.sh

2. Restore a specific backup:

/srv/backups/scripts/restore-vaultwarden.sh 20251210_050042

Warning: Restore will:

• Stop the Vaultwarden container
• Replace the PostgreSQL database
• Replace data directory files
• Restart the container

Retention Policy

• Backups older than 30 days are automatically deleted
• To change retention, edit RETENTION_DAYS in backup-vaultwarden.sh

Off-Site Backup Recommendations

The backup directory is stored locally. For disaster recovery, consider:

1. Sync to another server:

# Using rsync
rsync -avz /srv/backups/vaultwarden/ user@backup-server:/backups/vaultwarden/

2. Upload to cloud storage (S3, Backblaze B2, etc.):

# Using rclone (example)
rclone sync /srv/backups/vaultwarden/ remote:vaultwarden-backups/

3. Add to existing backup solution (e.g., Restic, Borg, Duplicati)

Testing Restores

Test your backups regularly:

# Test restore on a different machine or use a test database
PGDATABASE="vaultwarden_test" ./restore-vaultwarden.sh 20251210_050042

Backup Verification

Check backup integrity:

# List backup contents
docker run --rm -v /srv/backups/vaultwarden:/backup postgres:18-alpine \
  pg_restore --list /backup/vaultwarden_db_20251210_050042.dump | head -20

# Verify data archive
tar -tzf /srv/backups/vaultwarden/vaultwarden_data_20251210_050042.tar.gz

Troubleshooting

Backup fails with "Permission denied"

• Ensure the backup directory is writable by your user
• Check Docker has access to mount the backup directory

Restore fails with version mismatch

• Update the PostgreSQL Docker image version in restore script to match your database

Large backup sizes

• Database size grows with number of users and vault items
• Consider increasing retention period if backups are large
• Attachments are stored in the database (not as files)

Security Notes

• Backup files contain sensitive data (encrypted vault data + encryption keys)
• Protect backup directory with appropriate file permissions
• Encrypt backups before uploading to cloud storage
• Store .env file separately as it contains database credentials
• Backups are stored outside the git repository in /srv/backups/vaultwarden/