DSpace Backup Strategy with Borgmatic

This repository contains a template configuration for creating a robust, versioned, and encrypted backup solution for a DSpace repository using BorgBackup and Borgmatic.

It is the companion to this blog post.

Features

• 3-2-1 Compliant: Pre-configured for both a local and a remote SSH repository.
• Automated Database Dumps: Uses Borgmatic's built-in hooks for safe, consistent PostgreSQL backups.
• Efficient Storage: Leverages Borg's deduplication and zstd compression.
• Automated Pruning: Implements a sensible daily, weekly, and monthly retention policy.
• Health Checks: Includes built-in consistency checks to ensure your backups are not corrupt.

Prerequisites

To follow this guide, you will need the following installed on your DSpace server.

1. BorgBackup and Pipx: We will use pipx to install borgmatic in a clean, isolated environment. This is the officially recommended method.

   # Install BorgBackup and pipx from your system's package manager
   sudo apt-get update
   sudo apt-get install borgbackup pipx

2. Borgmatic: Install borgmatic using pipx.

   # Ensure pipx-installed apps are in your PATH
   pipx ensurepath
   
   # Install borgmatic
   pipx install borgmatic
   
   # You may need to log out and log back in for the PATH change to take effect.
   # Verify the installation:
   borgmatic --version

   Note: By installing this way, the borgmatic executable will likely be located at ~/.local/bin/borgmatic. Remember to use this full path in your cron job.

3. PostgreSQL Client: The pg_dump command is required for the database hook.

   sudo apt-get install postgresql-client

   Note: The postgresql-client should already be available if the database is running on the same server. This is just failsafe.

4. Remote Server Setup:

   • SSH Access: You need key-based SSH access to a remote backup server.
   • Borg on Remote: The remote server must also have borgbackup installed (sudo apt install borgbackup). It does not need borgmatic.

Step-by-Step Setup

1. Configure ~/.borgmatic.yml:

   • Copy the borgmatic.example.yml file to ~/.borgmatic.yml.
   • Update source_directories and repositories paths.
   • Update the database name in name under postgresql_databases if it's different.

2. Set Up Encryption (borgmatic.env):

   • Create a file at ~/.borgmatic.env with the following content.

   BORG_REPO=/opt/backup-repo
   BORG_PASSPHRASE='your-very-strong-encryption-password'
   

   • Set secure permissions: chmod 600 ~/.borgmatic.env.

3. Include borgmatic.env in .bashrc:

   • Add this line in ~/.bashrc.

   source .borgmatic.env
   

4. Set Up Database Password (.pgpass):

   • In the home directory of the user running the backup (e.g., /root/.pgpass), create a .pgpass file:

   # hostname:port:database:username:password
   localhost:5432:dspace:dspace:your-db-password
   

   • Set secure permissions: chmod 600 ~/.pgpass.

5. Initialize Repositories:

   # On the DSpace server (for local repo)
   borg init --encryption=repokey /opt/backup-repo
   
   # On the DSpace server (for remote repo)
   borg init --encryption=repokey ssh://user@remote-host/~/borg-repo

6. Create a Cron Job:

   • Edit the crontab for the user who will run the backups (e.g., crontab -e as the dspace user).
   • Add a line to run the backup daily. This example runs at 2:30 AM and uses the full path provided by pipx to avoid PATH issues.

   # Note the full path to the pipx-installed borgmatic binary.
   # Find the correct path by running: which borgmatic
   # It is typically ~/.local/bin/borgmatic
   30 2 * * * /home/dspace/.local/bin/borgmatic --config ~/.borgmatic.yml >> /tmp/borgmatic.log 2>&1

   If you are running the cron job as root, the path would be /root/.local/bin/borgmatic.

How to Restore

Scenario 1: Restore a single accidentally deleted file/folder

# List all available archives
borgmatic list

# Mount a specific archive as a filesystem
borg mount ssh://user@remote-host/~/borg-repo::dspace-2023-10-27T02:30:01 /mnt/borg-restore

# Now you can browse /mnt/borg-restore and copy the files you need!
rsync -avz --progress /mnt/borg-restore/opt/dspace/backend/assetstore /tmp/

# Unmount when done
borg umount /mnt/borg-restore

Scenario 2: Full disaster recovery

# Restore the latest archive to a new location
borgmatic extract --archive latest --destination /opt/dspace/restored_backend

An Alternative: Restic

This guide focuses on BorgBackup and Borgmatic because of their maturity, powerful compression options, and the simple declarative configuration offered by Borgmatic.

A fantastic, well-regarded alternative in this space is Restic. It shares the same core principles of client-side encryption and deduplication. Restic has different strengths, particularly its simplified design and excellent native support for a wide variety of cloud storage backends (like S3, B2, Azure). If you are primarily targeting cloud object storage, Restic is an excellent choice to investigate.