ddbb

ddbb, for Docker DataBase Backup, is a tool to manage dumps of docker stacks databases.

The purpose isn't to manage full versionning, RPO, RTO, etc. I just want something simple to dump databases to a local file, that my backup tool would next handle.

This means this tool targets Docker databases only, and relies heavily on Docker API and labels.

Installation and prerequisites

Use this compose.yaml as a base example:

services:
  ddbb:
    image: ramiuslr/ddbb
    container_name: ddbb
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - <your local dump directory>:/backups
    networks:
      - ddbb
    ports:
      - 3000:3000
    environment:
      BACKUP_CRON: "0 11,23 * * *"

networks:
  ddbb:
    name: ddbb

The BACKUP_CRON variable is the cron variable format to schedule automatic databases dumps. You can check syntax on https://crontab.guru/.

Then you can run it with:

docker compose up -d

Please note that the container should have access to your databases networks, and the Docker socket.

You also need to declare your database credentials using variables, as show in the example below.

This tool has only been tested locally for now, and support only:

• mariadb
• postgres
• mongodb

Usage

Setting up the targets

When you want to manage a database with ddbb, you just need to add two labels to its Compose manifest, for example:

services:
  mariadb:
    image: mariadb:11.8.2
    container_name: mariadb
    restart: always
    expose:
      - 3306
    environment:
      MARIADB_RANDOM_ROOT_PASSWORD: true
      MARIADB_USER: <username>
      MARIADB_PASSWORD: <password>
      MARIADB_DATABASE: <database>
    volumes:
      - ./mariadb:/var/lib/mysql
    networks:
      - ddbb
    labels:
      ddbb.enable: true
      ddbb.kind: mariadb

The kind can be one of those:

• mariadb
• postgres
• mongodb

The tool will then "see" your database and be able to connect to it, to perform the following actions:

• Dump
• Restore
• Integrity check

Using web interface

Head to http://<host>:3000, you'll have a dashboard to manage your dumps.

You're responsible of authentication and TLS, these are not automatically set up by this tool. I recommend running behind a reverse proxy such as Traefik to handle basic auth middleware, and Let's Encrypt certificates.

An orther solution would be to use a tool like Authelia to secure access.

Using API

Available API commands are:

Endpoint	Method	Arguments	Response
/list	GET	nil	Job List
/dump	POST	{id=<job id>}	Backup Job Result
/restore	POST	{id=<job id>}	Restore Job Result
/check-integrity	POST	{id=<job id>}	Job Integrity Status

Building yourself

There is a Justfile (Makefile alternative), which produces a Docker image, so this is pretty simple:

just run

Contributing

Every suggestion, issue, or PR is very welcome !

However, please note that I am developing this on my spare time, so I can't guarantee response time, release dates, etc.