Skip to content

Commit 42bc149

Browse files
rizlasrizlas
committed
feat: readme
1 parent 679c13e commit 42bc149

File tree

1 file changed

+153
-0
lines changed

1 file changed

+153
-0
lines changed

‎README.md

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,154 @@
11
# postgres-backup-owncloud
2+
3+
Postgres-backup-owncloud provides a simple solution for automating PostgreSQL database
4+
backups, encrypting them via GPG, and securely uploading them to an OwnCloud server.
5+
This is based on multiple solutions already available on github, main two are:
6+
7+
- [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local)
8+
- [postgres-backup-s3](https://github.com/eeshugerman/postgres-backup-s3)
9+
10+
A [docker image](https://hub.docker.com/r/rizl4s/postgres-backup-owncloud) is provided,
11+
therefore it can be used in any environment that support containers.
12+
13+
Backups are cron based using [go-cron](https://github.com/prodrigestivill/go-cron).
14+
15+
## Environment variables
16+
17+
| Name | Description | Default |
18+
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
19+
| BACKUP_KEEP_DAYS | Number of daily backups to keep before removal. | 7 |
20+
| SCHEDULE | [Cron-schedule](http://godoc.org/github.com/robfig/cron#hdr-Predefined_schedules) specifying the interval between postgres backups. | @daily |
21+
| HEALTHCHECK_PORT | Port listening for cron-schedule health check. | 8080 |
22+
| DRY_RUN | Test container functionality. It will not upload or restore dumps if set to true. | false |
23+
| RESTORE_MODE | Specifies where the backup should be restored from during the restore process. It defaults to 'remote', which means the backup will be fetched from OwnCloud. If set to 'local', the backup will be restored from a local directory specified in SHARE_PATH environment variable. | remote |
24+
| SHARE_PATH | Path to a shared ownCloud folder containing backups. Mandatory when using restore mode 'local'. | "" |
25+
| PGDUMP_EXTRA_OPTS | Additional options for pg_dump. | "" |
26+
| POSTGRES_HOST | Postgres connection parameter; postgres host to connect to. **Required**. | |
27+
| POSTGRES_PORT | Postgres connection parameter; postgres port to connect to. **Required**. | |
28+
| POSTGRES_DB | Postgres connection parameter; postgres database name to connect to. **Required**. | |
29+
| POSTGRES_PASSWORD | Postgres connection parameter; postgres password to connect with. **Required**. | |
30+
| POSTGRES_USER | Postgres connection parameter; postgres user to connect with. **Required**. | |
31+
| OWNCLOUD_FQDN | ownCloud FQDN without protocol (Fixed protocol is https, no http). **Required**. | |
32+
| OWNCLOUD_SHARE_ID | ownCloud public share ID. **Required**. | |
33+
| OWNCLOUD_SHARE_PASSWORD | ownCloud share password. **Required**. | |
34+
| PASSPHRASE | Passphrase used to encrypt or decrypt dumps. | |
35+
| GPG_EMAILS | Comma separated list of emails that will be used to encrypt dumps. This will take precedence over PASSPHRASE. | "" |
36+
| GPG_TRUST_MODEL | Set what trust model GnuPG should follow. Check gpg manual for available options. | auto |
37+
| GPG_KEY_LOCATE | Set retrieval mechanism when encrypting with an email address. Check gpg manual for available options. | wkd |
38+
| GPG_RESTORE_EMAIL | Email used to decrypt dumps. | |
39+
| GPG_RESTORE_EMAIL_PASSPHRASE | Passphrase of the private GPG key. Use this if you want to avoid user interaction. | |
40+
| WEBHOOK_URL | URL to be called after an error or after a successful backup (POST with a JSON payload, check hooks/00-webhook file for more info). | "" |
41+
| WEBHOOK_ERROR_URL | URL to be called in case backup fails. | "" |
42+
| WEBHOOK_PRE_BACKUP_URL | URL to be called when backup starts. | "" |
43+
| WEBHOOK_POST_BACKUP_URL | URL to be called when backup completes successfully. | "" |
44+
| WEBHOOK_EXTRA_ARGS | Extra arguments for the curl execution in the webhook (check hooks/00-webhook file for more info). | "" |
45+
| TZ | Container timezone. | UTC |
46+
47+
## GPG Encryption
48+
49+
The script supports two modes of encryption:
50+
51+
1. Using a GPG public key. Specify the email in the GPG_EMAILS environment variable. The
52+
backup will be encrypted using the provided GPG emails.
53+
54+
2. Using a passphrase. If no GPG public key is provided, set the PASSPHRASE environment
55+
variable to encrypt the backup using a passphrase.
56+
57+
Encryption is optional. If neither GPG_EMAILS nor PASSPHRASE is provided, the backup
58+
will not be encrypted.
59+
60+
## Usage
61+
62+
Once the environment variables are set (e.g. postgres.env, pgbackups.env), you can fire
63+
up the stack using the provided `docker-compose.yml`. You should modify it to fit your
64+
needs.
65+
66+
## Development
67+
68+
### Build the image locally
69+
70+
It is also possibile to leverage the docker compose to build the image locally, using:
71+
72+
```bash
73+
docker compose up -d --build --force-recreate
74+
```
75+
76+
### Run a simple test environment with Docker Compose
77+
78+
```sh
79+
cp example.env pgbackups.env
80+
# fill out your secrets/params in .env
81+
docker compose up -d
82+
```
83+
84+
### Development of get_backups.py
85+
86+
1. Get an xml file with curl
87+
88+
```bash
89+
cd src
90+
curl -s -X PROPFIND -u "$OWNCLOUD_SHARE_ID:$OWNCLOUD_SHARE_PASSWORD" \
91+
https://$OWNCLOUD_FQDN/public.php/webdav -o test.xml
92+
```
93+
94+
2. Make adjustment and run the script. For example
95+
96+
```bash
97+
python3 get_backups.py latest --xml-file test.xml --database-name postgres --passphrase-crypted
98+
```
99+
100+
## Hooks
101+
102+
The folder `hooks` inside the container can contain hooks/scripts to be run in
103+
differrent cases getting the exact situation as a first argument (`error`, `pre-backup`
104+
or `post-backup`).
105+
106+
Just create an script in that folder with execution permission so that
107+
[run-parts](https://manpages.debian.org/stable/debianutils/run-parts.8.en.html) can
108+
execute it on each state change.
109+
110+
Please, as an example take a look in the script already present there that implements
111+
the `WEBHOOK_URL` functionality.
112+
113+
## Manual backups
114+
115+
```bash
116+
docker exec -it cron-remote-backup-test sh
117+
sh backup.sh
118+
```
119+
120+
## Restore example
121+
122+
> [!CAUTION]
123+
> DATA LOSS! Target database will be dropped and re-created.
124+
125+
```bash
126+
docker exec -it cron-remote-backup-test sh
127+
sh restore.sh
128+
```
129+
130+
> [!NOTE]
131+
> If GPG_RESTORE_EMAIL and GPG_RESTORE_EMAIL_PASSPHRASE env vars are set, restore will
132+
> continue without the need of user inputs. Otherwise if only GPG_RESTORE_EMAIL is set
133+
> user must enter passphrase to unlock the key.
134+
135+
### Restore modes
136+
137+
1. Restore mode 'remote'
138+
139+
- Lastest backup will be downloaded from ownCloud and restored
140+
141+
2. Restore mode 'local'. You must also set SHARE_PATH env var.
142+
143+
- You must mount in the docker container your local shared folder where backups are
144+
stored
145+
- Lastest backup from the mounted directory will be used and restored
146+
147+
---
148+
149+
Feel free to make pull requests, fork, destroy or whatever you like most. Any criticism is more than welcome.
150+
151+
<br/>
152+
153+
<div align="center"><img src="https://avatars1.githubusercontent.com/u/8522635?s=96&v=4"/></div>
154+
<p align="center">#followtheturtle</p>

0 commit comments

Comments
 (0)