/
/
/
Ansible role that can run restic backups and push it to a remote storage server.
1# Role: backup\_compose
2
3Rolling backups for Docker Compose v2 projects using **restic**. Stops each service, backs up its data paths, pushes to a restic repo, then restarts the service. Includes health checks before/after.
4
5---
6
7## Features
8
9* Stop one Compose project at a time for a consistent snapshot
10* Back up specified paths with restic
11* Initialize restic repo if missing
12* Optional retention policy (`restic forget --prune`)
13* Health check containers before/after backup
14* Optional pre/post shell commands per service
15* Idempotent, safe for repeated runs
16
17---
18
19## Variables
20
21```yaml
22backup_services:
23 - name: app1
24 path: /opt/stacks/app1
25 targets:
26 - /srv/data/app1
27 - /opt/stacks/app1
28 pre_cmd: ["echo pre"]
29 post_cmd: ["echo post"]
30
31restic_repo: "sftp:user@backup:/repos/host1"
32restic_password: "..." # vault this
33restic_backup_args: "--one-file-system"
34restic_retention_enable: true
35restic_retention_args: "--keep-daily 7 --keep-weekly 4 --keep-monthly 6"
36
37backup_health_check: true
38backup_health_timeout_sec: 600
39backup_health_interval_sec: 5
40```
41
42---
43
44## Example Play
45
46```yaml
47- hosts: docker_hosts
48 become: true
49 roles:
50 - role: backup_compose
51 vars:
52 restic_repo: "sftp:backup@backuphost:/repos/{{ inventory_hostname }}"
53 restic_password: !vault | ...
54 backup_services:
55 - name: traefik
56 path: /opt/stacks/traefik
57 targets:
58 - /opt/stacks/traefik
59 - name: app1
60 path: /opt/stacks/app1
61 targets:
62 - /srv/data/app1
63```
64
65---
66
67## Tags
68
69* `backup`
70* `restic`
71* `validate`
72
73---
74
75## Requirements
76
77* Debian/Ubuntu host (restic installed automatically if `backup_install_restic: true`)
78* `community.docker` collection (for `docker_compose_v2` and container info)
79
80Install:
81
82```bash
83ansible-galaxy collection install community.docker
84```
85
86---
87
88# Role: backup\_compose
89
90Rolling **restic** backups for Docker Compose v2 projects. Stops one project at a time, backs up specified host paths, enforces retention, and brings it back healthy.
91
92## Features
93
94* Perâproject rolling backup (stop â backup â start)
95* Health checks before/after via container `HEALTHCHECK`
96* Restic repo autoâinit + retention (`forget --prune`)
97* Works with SFTP/S3/B2/etc. via env
98* Sequential processing to limit impact
99
100## Variables
101
102```yaml
103backup_services:
104 - name: app1
105 path: /opt/stacks/app1 # compose project directory
106 targets: [/srv/data/app1, /opt/stacks/app1] # host paths to back up
107 project_name: app1 # optional (defaults to basename(path))
108 compose_files: [] # optional custom compose files
109 pre_cmd: [] # optional host commands before stop
110 post_cmd: [] # optional host commands after start
111
112restic_repo: "sftp:user@host:/repos/{{ inventory_hostname }}"
113restic_password: "<vaulted>"
114restic_env_extra: {} # e.g. AWS creds for S3/B2
115restic_backup_args: "--one-file-system"
116restic_tag_format: "{{ item.name | default(item.path | basename) }}"
117restic_retention_enable: true
118restic_retention_args: "--keep-daily 7 --keep-weekly 4 --keep-monthly 6"
119
120backup_health_check: true
121backup_health_timeout_sec: 600
122backup_health_interval_sec: 5
123
124backup_install_restic: true # install restic via apt
125backup_restic_pkg_name: restic
126```
127
128## Example
129
130```yaml
131- hosts: docker_hosts
132 become: true
133 roles:
134 - role: backup_compose
135 vars:
136 restic_repo: "sftp:backup@backuphost:/repos/{{ inventory_hostname }}"
137 restic_password: !vault | <vaulted>
138 backup_services:
139 - name: traefik
140 path: /opt/stacks/traefik
141 targets: [/opt/stacks/traefik]
142 - name: app1
143 path: /opt/stacks/app1
144 targets: [/srv/data/app1, /opt/stacks/app1]
145```
146
147## Notes
148
149* Requires `community.docker` collection (Compose v2 module)
150
151 ```bash
152 ansible-galaxy collection install community.docker
153 ```
154* Put secrets (restic password, cloud creds) in **Ansible Vault**.
155
156