backup-bot-two/README.md

# Backupbot II

Wiki Cafe's configuration for a Backupbot II deployment. Originally slimmed down from an `abra` [recipe](https://git.coopcloud.tech/coop-cloud/backup-bot-two) by [Co-op Cloud](https://coopcloud.tech/).


## Deploying the app with Docker Swarm

Set the environment variables from the .env file during the shell session.

```
set -a && source .env && set +a
```

Set the secrets.

```
printf "SECRET_HERE" | docker secret create SECRET_NAME -
```

Deploy using the `-c` flag to specify one or multiple compose files.

```
docker stack deploy backup-bot-two -c compose.yaml
```

## Push notifications

The following env variables can be used to setup push notifications for backups. `PUSH_URL_START` is requested just before the backups starts, `PUSH_URL_SUCCESS` is only requested if the backup was successful and if the backup fails `PUSH_URL_FAIL` will be requested.
Each variable is optional and independent of the other.
```

PUSH_URL_START=https://status.example.com/api/push/xxxxxxxxxx?status=up&msg=start
PUSH_URL_SUCCESS=https://status.example.com/api/push/xxxxxxxxxx?status=up&msg=OK
PUSH_URL_FAIL=https://status.example.com/api/push/xxxxxxxxxx?status=down&msg=fail
```

## Commands


- Find the ID or name of the backup container:
   ```
   docker ps --filter "name=backup-bot-two_app"
   ```

2. Run the desired command using `docker exec`:
   ```
   docker exec -it <container_id_or_name> backup <command> [options]
   ```
   Replace `<container_id_or_name>` with the ID or name of the backup container.

   Available commands:
   - `create`: Initiate the backup process.
   - `restore`: Restore a specific snapshot to a target directory.
   - `snapshots`: List available snapshots.
   - `ls`: List files in a specific snapshot.
   - `download`: Download specific files, volumes, or secrets from a snapshot.

   Options:
   - `--host`, `-h`: Specify the service name (e.g., `app`).
   - `--repo`, `-r`: Specify the Restic repository location (e.g., `/run/secrets/restic_repo`).
   - `--log`, `-l`: Set the log level (e.g., `debug`, `info`, `warning`, `error`).
   - `--machine-logs`, `-m`: Enable machine-readable JSON logging.

## Examples

Create a backup:

```
docker exec -it <container_id_or_name> backup create --host app
```

Restore a snapshot:

```
docker exec -it <container_id_or_name> backup restore --snapshot <snapshot_id> --target /path/to/restore
```

List snapshots:

  ```
  docker exec -it <container_id_or_name> backup snapshots
  ```

List files in a snapshot:

```
docker exec -it <container_id_or_name> backup ls --snapshot <snapshot_id> --path /path/to/directory
```

Download files, volumes, or secrets from a snapshot:

```
docker exec -it <container_id_or_name> backup download --snapshot <snapshot_id> [--path /path/to/file] [--volumes] [--secrets]
```

Note: Make sure to replace `<container_id_or_name>` and `<snapshot_id>` with the appropriate values for your setup.

Remember to review and adjust the Docker Compose file and environment variables according to your specific requirements before running the backup commands.

When using `docker exec`, you don't need to specify the volume mounts or the Restic repository location as command-line arguments because they are already defined in the Docker Compose file and are available within the running container.

If you need to access the downloaded files, volumes, or secrets from the backup, you can use `docker cp` to copy them from the container to the host machine:

```
docker cp <container_id_or_name>:/path/to/backup/file /path/on/host
```

This allows you to retrieve the backed-up data from the container.

## Recipe Configuration

Backupbot II uses access to the Docker socket to read labels from running Docker Swarm services:

```
services:
  db:
    deploy:
      labels:
        backupbot.backup: ${BACKUP:-"true"} 
        backupbot.backup.pre-hook: 'mysqldump -u root -p"$(cat /run/secrets/db_root_password)" -f /volume_path/dump.db'
        backupbot.backup.post-hook: "rm -rf /volume_path/dump.db"
```

- `backupbot.backup` -- set to `true` to back up this service (REQUIRED)
- `backupbot.backup.pre-hook` -- command to run before copying files (optional), save all dumps into the volumes
- `backupbot.backup.post-hook` -- command to run after copying files (optional)

As in the above example, you can reference Docker Secrets, e.g. for looking up database passwords, by reading the files in `/run/secrets` directly.