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:
```yaml
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:
```bash
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:
```yaml
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:
```bash
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.