# Borgmatic Backup System

> Borgmatic for automated Borg backups with scheduling.

- Category: Storage & Backup
- Difficulty: intermediate
- Components: borgmatic
- Tags: borg, borgmatic, backup, deduplication, automation
- Source: https://docker.recipes/storage/borgmatic-backup

## Overview

Borgmatic is a wrapper around BorgBackup that automates the process of creating, maintaining, and monitoring deduplicated backups. Created to simplify Borg's complex command-line interface, borgmatic provides declarative YAML configuration files and built-in scheduling capabilities, making enterprise-grade backup automation accessible to organizations of all sizes. The tool handles backup rotation, health checks, and repository maintenance automatically while preserving Borg's powerful deduplication and encryption features.

This Docker stack combines borgmatic with persistent storage volumes and configurable source directories to create a complete backup automation solution. The b3vis/borgmatic image includes cron scheduling and comprehensive logging, while Docker volumes ensure backup configurations and Borg caches survive container updates. The setup supports both local repositories and remote backup destinations including SSH, S3, and other cloud storage providers.

System administrators managing multiple servers, DevOps teams requiring automated backup workflows, and organizations needing compliance-ready backup retention policies will find this stack invaluable. The combination of Borg's space-efficient deduplication with borgmatic's automation reduces both storage costs and administrative overhead while maintaining enterprise-level reliability and security standards.

## Features

- Automated backup scheduling with configurable retention policies and pruning rules
- BorgBackup deduplication engine reducing storage requirements by 80-95% for typical datasets
- Built-in health checks with configurable monitoring hooks for external alerting systems
- Support for multiple repository types including local, SSH, S3, and other cloud providers
- Automatic repository maintenance including compact operations and consistency checks
- Comprehensive logging and error reporting with customizable notification channels
- YAML-based configuration supporting multiple backup jobs and complex filtering rules
- Integration with monitoring systems through healthchecks.io, Prometheus, and webhook notifications

## Use cases

- Automated server backup workflows for production infrastructure with compliance requirements
- Development team data protection for source code repositories and build artifacts
- Database backup automation with point-in-time recovery capabilities
- Homelab and personal server backup management with minimal maintenance overhead
- Multi-tenant backup solutions for managed service providers
- Disaster recovery systems requiring offsite replication and encrypted storage
- Container volume backup for stateful applications in Docker and Kubernetes environments

## Prerequisites

- Minimum 512MB RAM for small repositories, 2GB+ recommended for large datasets
- Sufficient disk space for Borg cache (typically 1-2% of total backup size)
- Network access to backup repositories if using remote storage destinations
- Understanding of Borg repository initialization and passphrase management
- Familiarity with YAML configuration syntax for borgmatic setup files
- SSH key configuration if backing up to remote repositories via SSH protocol

## docker-compose.yml

```yaml
services:
  borgmatic:
    image: b3vis/borgmatic:latest
    container_name: borgmatic
    restart: unless-stopped
    environment:
      - TZ=${TZ:-UTC}
      - BORG_PASSPHRASE=${BORG_PASSPHRASE:-}
    volumes:
      - ./borgmatic.d:/etc/borgmatic.d:ro
      - ${SOURCE_PATH:-./source}:/mnt/source:ro
      - ${REPO_PATH:-./repo}:/mnt/borg-repository
      - borgmatic_config:/root/.config/borg
      - borgmatic_cache:/root/.cache/borg
    networks:
      - borgmatic-network

volumes:
  borgmatic_config:
  borgmatic_cache:

networks:
  borgmatic-network:
    driver: bridge
```

## .env

```bash
# Borgmatic
TZ=UTC
BORG_PASSPHRASE=your-secure-passphrase
SOURCE_PATH=./source
REPO_PATH=./repo
```

## Usage notes

- Create borgmatic.d/config.yaml
- Run borgmatic init first
- Cron scheduling built-in
- Supports remote repositories

## Troubleshooting

- Repository does not exist error: Run 'borgmatic init' to initialize the repository before first backup
- Permission denied accessing source files: Ensure Docker container has read access to source directories and proper UID mapping
- Borg cache lock timeout errors: Remove stale lock files from borgmatic_cache volume or increase lock timeout values
- Out of disk space during backup: Configure appropriate pruning policies and monitor repository growth patterns
- Failed to create/acquire the lock: Stop any running borgmatic processes and remove lock files from the repository
- Backup verification failures: Check repository integrity with 'borg check' and verify source data hasn't been corrupted

