diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 0000000..5e1108f --- /dev/null +++ b/docs/Dockerfile @@ -0,0 +1,12 @@ +FROM ruby:3.3.4 + +ENV LC_ALL C.UTF-8 +ENV LANG en_US.UTF-8 +ENV LANGUAGE en_US.UTF-8 + +WORKDIR /usr/src/app + +COPY . ./ +RUN gem install bundler && bundle install + +EXPOSE 4000 \ No newline at end of file diff --git a/docs/_config.yml b/docs/_config.yml index 69ddbbd..acbe473 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -19,8 +19,8 @@ description: >- # this means to ignore newlines until "baseurl:" PostgreSQL Backup is a Docker container image that can be used to backup and restore Postgres database. It supports local storage, AWS S3 or any S3 Alternatives for Object Storage, and SSH compatible storage. -baseurl: "https://jkaninda.github.io/mysql-bkup/" # the subpath of your site, e.g. /blog -url: "jkaninda.github.io/pg-bkup/" # the base hostname & protocol for your site, e.g. http://example.com +baseurl: "" # the subpath of your site, e.g. /blog +url: "" # the base hostname & protocol for your site, e.g. http://example.com twitter_username: jonaskaninda github_username: jkaninda diff --git a/docs/reference/index.md b/docs/reference/index.md index faf78a5..8385ef1 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -4,139 +4,123 @@ layout: default nav_order: 3 --- -# Configuration reference - -Backup, restore and migrate targets, schedule and retention are configured using environment variables or flags. - - - - - -### CLI utility Usage - -| Options | Shorts | Usage | -|-----------------------|--------|----------------------------------------------------------------------------------------| -| pg-bkup | bkup | CLI utility | -| backup | | Backup database operation | -| restore | | Restore database operation | -| migrate | | Migrate database from one instance to another one | -| --storage | -s | Storage. local or s3 (default: local) | -| --file | -f | File name for restoration | -| --path | | AWS S3 path without file name. eg: /custom_path or ssh remote path `/home/foo/backup` | -| --dbname | -d | Database name | -| --port | -p | Database port (default: 5432) | -| --disable-compression | | Disable database backup compression | -| --cron-expression | | Backup cron expression, eg: (* * * * *) or @daily | -| --help | -h | Print this help message and exit | -| --version | -V | Print version information and exit | - -## Environment variables - -| Name | Requirement | Description | -|------------------------------|---------------------------------------------------------------|-----------------------------------------------------------------| -| DB_PORT | Optional, default 5432 | Database port number | -| DB_HOST | Required | Database host | -| DB_NAME | Optional if it was provided from the -d flag | Database name | -| DB_USERNAME | Required | Database user name | -| DB_PASSWORD | Required | Database password | -| DB_URL | Optional | Database URL in JDBC URI format | -| AWS_ACCESS_KEY | Optional, required for S3 storage | AWS S3 Access Key | -| AWS_SECRET_KEY | Optional, required for S3 storage | AWS S3 Secret Key | -| AWS_BUCKET_NAME | Optional, required for S3 storage | AWS S3 Bucket Name | -| AWS_BUCKET_NAME | Optional, required for S3 storage | AWS S3 Bucket Name | -| AWS_REGION | Optional, required for S3 storage | AWS Region | -| AWS_DISABLE_SSL | Optional, required for S3 storage | Disable SSL | -| AWS_FORCE_PATH_STYLE | Optional, required for S3 storage | Force path style | -| FILE_NAME | Optional if it was provided from the --file flag | Database file to restore (extensions: .sql, .sql.gz) | -| GPG_PASSPHRASE | Optional, required to encrypt and restore backup | GPG passphrase | -| GPG_PUBLIC_KEY | Optional, required to encrypt backup | GPG public key, used to encrypt backup (/config/public_key.asc) | -| BACKUP_CRON_EXPRESSION | Optional if it was provided from the `--cron-expression` flag | Backup cron expression for docker in scheduled mode | -| BACKUP_RETENTION_DAYS | Optional | Delete old backup created more than specified days ago | -| SSH_HOST | Optional, required for SSH storage | ssh remote hostname or ip | -| SSH_USER | Optional, required for SSH storage | ssh remote user | -| SSH_PASSWORD | Optional, required for SSH storage | ssh remote user's password | -| SSH_IDENTIFY_FILE | Optional, required for SSH storage | ssh remote user's private key | -| SSH_PORT | Optional, required for SSH storage | ssh remote server port | -| REMOTE_PATH | Optional, required for SSH or FTP storage | remote path (/home/toto/backup) | -| FTP_HOST | Optional, required for FTP storage | FTP host name | -| FTP_PORT | Optional, required for FTP storage | FTP server port number | -| FTP_USER | Optional, required for FTP storage | FTP user | -| FTP_PASSWORD | Optional, required for FTP storage | FTP user password | -| TARGET_DB_HOST | Optional, required for database migration | Target database host | -| TARGET_DB_PORT | Optional, required for database migration | Target database port | -| TARGET_DB_NAME | Optional, required for database migration | Target database name | -| TARGET_DB_USERNAME | Optional, required for database migration | Target database username | -| TARGET_DB_URL | Optional | Database URL in JDBC URI format | -| TARGET_DB_PASSWORD | Optional, required for database migration | Target database password | -| TG_TOKEN | Optional, required for Telegram notification | Telegram token (`BOT-ID:BOT-TOKEN`) | -| TG_CHAT_ID | Optional, required for Telegram notification | Telegram Chat ID | -| TZ | Optional | Time Zone | -| AZURE_STORAGE_CONTAINER_NAME | Optional, required for Azure Blob Storage storage | Azure storage container name | -| AZURE_STORAGE_ACCOUNT_NAME | Optional, required for Azure Blob Storage storage | Azure storage account name | -| AZURE_STORAGE_ACCOUNT_KEY | Optional, required for Azure Blob Storage storage | Azure storage account key | +# Configuration Reference + +Backup, restore, and migration targets, schedules, and retention policies are configured using **environment variables** or **CLI flags**. --- -## Run in Scheduled mode -This image can be run as CronJob in Kubernetes for a regular backup which makes deployment on Kubernetes easy as Kubernetes has CronJob resources. -For Docker, you need to run it in scheduled mode by adding `--cron-expression "* * * * *"` flag or by defining `BACKUP_CRON_EXPRESSION=0 1 * * *` environment variable. +## CLI Utility Usage + +| Option | Short Flag | Description | +|-------------------------|------------|-------------------------------------------------------------------------------| +| `pg-bkup` | `bkup` | CLI utility for managing PostgreSQL backups. | +| `backup` | | Perform a backup operation. | +| `restore` | | Perform a restore operation. | +| `migrate` | | Migrate a database from one instance to another. | +| `--storage` | `-s` | Storage type (`local`, `s3`, `ssh`, etc.). Default: `local`. | +| `--file` | `-f` | File name for restoration. | +| `--path` | | Path for storage (e.g., `/custom_path` for S3 or `/home/foo/backup` for SSH). | +| `--dbname` | `-d` | Database name. | +| `--port` | `-p` | Database port. Default: `5432`. | +| `--disable-compression` | | Disable compression for database backups. | +| `--cron-expression` | | Cron expression for scheduled backups (e.g., `* * * * *` or `@daily`). | +| `--help` | `-h` | Display help message and exit. | +| `--version` | `-V` | Display version information and exit. | -## Syntax of crontab (field description) +--- -The syntax is: +## Environment Variables + +| Name | Requirement | Description | +|--------------------------------|--------------------------------------|-------------------------------------------------------------------------| +| `DB_PORT` | Optional (default: `5432`) | Database port number. | +| `DB_HOST` | Required | Database host. | +| `DB_NAME` | Optional (if provided via `-d` flag) | Database name. | +| `DB_USERNAME` | Required | Database username. | +| `DB_PASSWORD` | Required | Database password. | +| `DB_URL` | Optional | Database URL in JDBC URI format. | +| `AWS_ACCESS_KEY` | Required for S3 storage | AWS S3 Access Key. | +| `AWS_SECRET_KEY` | Required for S3 storage | AWS S3 Secret Key. | +| `AWS_BUCKET_NAME` | Required for S3 storage | AWS S3 Bucket Name. | +| `AWS_REGION` | Required for S3 storage | AWS Region. | +| `AWS_DISABLE_SSL` | Optional | Disable SSL for S3 storage. | +| `AWS_FORCE_PATH_STYLE` | Optional | Force path-style access for S3 storage. | +| `FILE_NAME` | Optional (if provided via `--file`) | File name for restoration (e.g., `.sql`, `.sql.gz`). | +| `GPG_PASSPHRASE` | Optional | GPG passphrase for encrypting/decrypting backups. | +| `GPG_PUBLIC_KEY` | Optional | GPG public key for encrypting backups (e.g., `/config/public_key.asc`). | +| `BACKUP_CRON_EXPRESSION` | Optional | Cron expression for scheduled backups. | +| `BACKUP_RETENTION_DAYS` | Optional | Delete backups older than the specified number of days. | +| `SSH_HOST` | Required for SSH storage | SSH remote hostname or IP. | +| `SSH_USER` | Required for SSH storage | SSH remote username. | +| `SSH_PASSWORD` | Optional | SSH remote user's password. | +| `SSH_IDENTIFY_FILE` | Optional | SSH remote user's private key. | +| `SSH_PORT` | Optional (default: `22`) | SSH remote server port. | +| `REMOTE_PATH` | Required for SSH/FTP storage | Remote path (e.g., `/home/toto/backup`). | +| `FTP_HOST` | Required for FTP storage | FTP hostname. | +| `FTP_PORT` | Optional (default: `21`) | FTP server port. | +| `FTP_USER` | Required for FTP storage | FTP username. | +| `FTP_PASSWORD` | Required for FTP storage | FTP user password. | +| `TARGET_DB_HOST` | Required for migration | Target database host. | +| `TARGET_DB_PORT` | Optional (default: `5432`) | Target database port. | +| `TARGET_DB_NAME` | Required for migration | Target database name. | +| `TARGET_DB_USERNAME` | Required for migration | Target database username. | +| `TARGET_DB_PASSWORD` | Required for migration | Target database password. | +| `TARGET_DB_URL` | Optional | Target database URL in JDBC URI format. | +| `TG_TOKEN` | Required for Telegram notifications | Telegram token (`BOT-ID:BOT-TOKEN`). | +| `TG_CHAT_ID` | Required for Telegram notifications | Telegram Chat ID. | +| `TZ` | Optional | Time zone for scheduling. | +| `AZURE_STORAGE_CONTAINER_NAME` | Required for Azure Blob Storage | Azure storage container name. | +| `AZURE_STORAGE_ACCOUNT_NAME` | Required for Azure Blob Storage | Azure storage account name. | +| `AZURE_STORAGE_ACCOUNT_KEY` | Required for Azure Blob Storage | Azure storage account key. | -- 1: Minute (0-59) -- 2: Hours (0-23) -- 3: Day (0-31) -- 4: Month (0-12 [12 == December]) -- 5: Day of the week(0-7 [7 or 0 == sunday]) +--- -Easy to remember format: +## Scheduled Backups -```conf -* * * * * command to be executed -``` +### Running in Scheduled Mode -```conf -- - - - - -| | | | | -| | | | ----- Day of week (0 - 7) (Sunday=0 or 7) -| | | ------- Month (1 - 12) -| | --------- Day of month (1 - 31) -| ----------- Hour (0 - 23) -------------- Minute (0 - 59) -``` +- **Docker**: Use the `--cron-expression` flag or the `BACKUP_CRON_EXPRESSION` environment variable to schedule backups. +- **Kubernetes**: Use a `CronJob` resource for scheduled backups. -> At every 30th minute +### Cron Syntax + +The cron syntax consists of five fields: ```conf -*/30 * * * * -``` -> “At minute 0.” every hour -```conf -0 * * * * +* * * * * command ``` -> “At 01:00.” every day +| Field | Description | Values | +|---------------|------------------------------|----------------| +| Minute | Minute of the hour | `0-59` | +| Hour | Hour of the day | `0-23` | +| Day of Month | Day of the month | `1-31` | +| Month | Month of the year | `1-12` | +| Day of Week | Day of the week (0 = Sunday) | `0-7` | -```conf -0 1 * * * -``` -## Predefined schedules -You may use one of several pre-defined schedules in place of a cron expression. +#### Examples + +- **Every 30 minutes**: `*/30 * * * *` +- **Every hour at minute 0**: `0 * * * *` +- **Every day at 1:00 AM**: `0 1 * * *` -| Entry | Description | Equivalent To | -|------------------------|--------------------------------------------|---------------| -| @yearly (or @annually) | Run once a year, midnight, Jan. 1st | 0 0 1 1 * | -| @monthly | Run once a month, midnight, first of month | 0 0 1 * * | -| @weekly | Run once a week, midnight between Sat/Sun | 0 0 * * 0 | -| @daily (or @midnight) | Run once a day, midnight | 0 0 * * * | -| @hourly | Run once an hour, beginning of hour | 0 * * * * | +### Predefined Schedules + +| Entry | Description | Equivalent To | +|----------------------------|--------------------------------------------|---------------| +| `@yearly` (or `@annually`) | Run once a year, midnight, Jan. 1st | `0 0 1 1 *` | +| `@monthly` | Run once a month, midnight, first of month | `0 0 1 * *` | +| `@weekly` | Run once a week, midnight between Sat/Sun | `0 0 * * 0` | +| `@daily` (or `@midnight`) | Run once a day, midnight | `0 0 * * *` | +| `@hourly` | Run once an hour, beginning of hour | `0 * * * *` | ### Intervals -You may also schedule backup task at fixed intervals, starting at the time it's added or cron is run. This is supported by formatting the cron spec like this: +You can also schedule backups at fixed intervals using the format: + +```conf @every -where "duration" is a string accepted by time. +``` -For example, "@every 1h30m10s" would indicate a schedule that activates after 1 hour, 30 minutes, 10 seconds, and then every interval after that. \ No newline at end of file +- Example: `@every 1h30m10s` runs the backup every 1 hour, 30 minutes, and 10 seconds.