diff --git a/README.md b/README.md index c5cdccc..db62ca0 100644 --- a/README.md +++ b/README.md @@ -65,52 +65,75 @@ Successfully tested on: - SSH remote storage server - FTP remote storage server - Azure Blob storage + ## Quickstart -### Simple backup using Docker CLI +### Simple Backup Using Docker CLI -To run a one time backup, bind your local volume to `/backup` in the container and run the `backup` command: +To perform a one-time backup, bind your local volume to `/backup` in the container and run the `backup` command: ```shell - docker run --rm --network your_network_name \ - -v $PWD/backup:/backup/ \ - -e "DB_HOST=dbhost" \ - -e "DB_PORT=3306" \ - -e "DB_USERNAME=username" \ - -e "DB_PASSWORD=password" \ - jkaninda/mysql-bkup backup -d database_name +docker run --rm --network your_network_name \ + -v $PWD/backup:/backup/ \ + -e "DB_HOST=dbhost" \ + -e "DB_PORT=3306" \ + -e "DB_USERNAME=username" \ + -e "DB_PASSWORD=password" \ + jkaninda/mysql-bkup backup -d database_name ``` -Alternatively, pass a `--env-file` in order to use a full config as described below. - -```yaml - docker run --rm --network your_network_name \ - --env-file your-env-file \ - -v $PWD/backup:/backup/ \ - jkaninda/mysql-bkup backup -d database_name -``` -### Simple restore using Docker CLI - -To restore a database, bind your local volume to `/backup` in the container and run the `restore` command: +Alternatively, use an environment file (`--env-file`) for configuration: ```shell - docker run --rm --network your_network_name \ - -v $PWD/backup:/backup/ \ - -e "DB_HOST=dbhost" \ - -e "DB_PORT=3306" \ - -e "DB_USERNAME=username" \ - -e "DB_PASSWORD=password" \ - jkaninda/mysql-bkup restore -d database_name -f backup_file.sql.gz +docker run --rm --network your_network_name \ + --env-file your-env-file \ + -v $PWD/backup:/backup/ \ + jkaninda/mysql-bkup backup -d database_name ``` -### Simple backup in docker compose file + +### Backup All Databases + +To back up all databases on the server, use the `--all-databases` or `-a` flag. By default, this creates individual backup files for each database. + +```shell +docker run --rm --network your_network_name \ + -v $PWD/backup:/backup/ \ + -e "DB_HOST=dbhost" \ + -e "DB_PORT=3306" \ + -e "DB_USERNAME=username" \ + -e "DB_PASSWORD=password" \ + jkaninda/mysql-bkup backup --all-databases --disable-compression +``` + +> **Note:** Use the `--all-in-one` or `-A` flag to combine backups into a single file. + +--- + +### Simple Restore Using Docker CLI + +To restore a database, bind your local volume to `/backup` and run the `restore` command: + +```shell +docker run --rm --network your_network_name \ + -v $PWD/backup:/backup/ \ + -e "DB_HOST=dbhost" \ + -e "DB_PORT=3306" \ + -e "DB_USERNAME=username" \ + -e "DB_PASSWORD=password" \ + jkaninda/mysql-bkup restore -d database_name -f backup_file.sql.gz +``` + +--- + +### Backup with Docker Compose + +Below is an example of a `docker-compose.yml` file for running a one-time backup: ```yaml services: - mysql-bkup: - # In production, it is advised to lock your image tag to a proper - # release version instead of using `latest`. - # Check https://github.com/jkaninda/mysql-bkup/releases - # for a list of available releases. + pg-bkup: + # In production, pin your image tag to a specific release version instead of `latest`. + # See available releases: https://github.com/jkaninda/mysql-bkup/releases image: jkaninda/mysql-bkup container_name: mysql-bkup command: backup @@ -123,29 +146,39 @@ services: - DB_USERNAME=bar - DB_PASSWORD=password - TZ=Europe/Paris - # mysql-bkup container must be connected to the same network with your database networks: - web + networks: web: ``` -### Docker recurring backup + +--- + +### Recurring Backups with Docker + +You can schedule recurring backups using the `--cron-expression` or `-e` flag: ```shell - docker run --rm --network network_name \ - -v $PWD/backup:/backup/ \ - -e "DB_HOST=hostname" \ - -e "DB_USERNAME=user" \ - -e "DB_PASSWORD=password" \ - jkaninda/mysql-bkup backup -d dbName --cron-expression "@every 15m" #@midnight +docker run --rm --network network_name \ + -v $PWD/backup:/backup/ \ + -e "DB_HOST=hostname" \ + -e "DB_USERNAME=user" \ + -e "DB_PASSWORD=password" \ + jkaninda/mysql-bkup backup -d dbName --cron-expression "@every 15m" ``` -See: https://jkaninda.github.io/mysql-bkup/reference/#predefined-schedules + +For predefined schedules, refer to the [documentation](https://jkaninda.github.io/mysql-bkup/reference/#predefined-schedules). + +--- ## Deploy on Kubernetes -For Kubernetes, you don't need to run it in scheduled mode. You can deploy it as Job or CronJob. +For Kubernetes, you can deploy `mysql-bkup` as a Job or CronJob. Below are examples for both. -### Simple Kubernetes backup Job : +### Kubernetes Backup Job + +This example defines a one-time backup job: ```yaml apiVersion: batch/v1 @@ -158,10 +191,8 @@ spec: spec: containers: - name: mysql-bkup - # In production, it is advised to lock your image tag to a proper - # release version instead of using `latest`. - # Check https://github.com/jkaninda/mysql-bkup/releases - # for a list of available releases. + # Pin the image tag to a specific release version in production. + # See available releases: https://github.com/jkaninda/mysql-bkup/releases image: jkaninda/mysql-bkup command: - /bin/sh @@ -184,10 +215,52 @@ spec: volumes: - name: backup hostPath: - path: /home/toto/backup # directory location on host - type: Directory # this field is optional + path: /home/toto/backup # Directory location on the host + type: Directory # Optional field restartPolicy: Never ``` + +### Kubernetes CronJob for Scheduled Backups + +For scheduled backups, use a `CronJob`: + +```yaml +apiVersion: batch/v1 +kind: CronJob +metadata: + name: pg-bkup-cronjob +spec: + schedule: "0 2 * * *" # Runs daily at 2 AM + jobTemplate: + spec: + template: + spec: + containers: + - name: pg-bkup + image: jkaninda/mysql-bkup + command: + - /bin/sh + - -c + - backup -d dbname + env: + - name: DB_HOST + value: "mysql" + - name: DB_USERNAME + value: "user" + - name: DB_PASSWORD + value: "password" + volumeMounts: + - mountPath: /backup + name: backup + volumes: + - name: backup + hostPath: + path: /home/toto/backup + type: Directory + restartPolicy: OnFailure +``` + +--- ## Available image registries This Docker image is published to both Docker Hub and the GitHub container registry. diff --git a/docs/quickstart/index.md b/docs/quickstart/index.md index 6437152..7638aad 100644 --- a/docs/quickstart/index.md +++ b/docs/quickstart/index.md @@ -10,11 +10,11 @@ This guide provides quick examples for running backups using Docker CLI, Docker --- -## Simple Backup Using Docker CLI +### Simple Backup Using Docker CLI -To run a one-time backup, bind your local volume to `/backup` in the container and execute the `backup` command: +To perform a one-time backup, bind your local volume to `/backup` in the container and run the `backup` command: -```bash +```shell docker run --rm --network your_network_name \ -v $PWD/backup:/backup/ \ -e "DB_HOST=dbhost" \ @@ -24,41 +24,58 @@ docker run --rm --network your_network_name \ jkaninda/mysql-bkup backup -d database_name ``` -### Using an Environment File +Alternatively, use an environment file (`--env-file`) for configuration: -Alternatively, you can use an `--env-file` to pass a full configuration: - -```bash +```shell docker run --rm --network your_network_name \ --env-file your-env-file \ -v $PWD/backup:/backup/ \ jkaninda/mysql-bkup backup -d database_name ``` -### Simple restore using Docker CLI +### Backup All Databases -To restore a database, bind your local volume to `/backup` in the container and run the `restore` command: +To back up all databases on the server, use the `--all-databases` or `-a` flag. By default, this creates individual backup files for each database. ```shell - docker run --rm --network your_network_name \ - -v $PWD/backup:/backup/ \ - -e "DB_HOST=dbhost" \ - -e "DB_PORT=3306" \ - -e "DB_USERNAME=username" \ - -e "DB_PASSWORD=password" \ - jkaninda/mysql-bkup restore -d database_name -f backup_file.sql.gz +docker run --rm --network your_network_name \ + -v $PWD/backup:/backup/ \ + -e "DB_HOST=dbhost" \ + -e "DB_PORT=3306" \ + -e "DB_USERNAME=username" \ + -e "DB_PASSWORD=password" \ + jkaninda/mysql-bkup backup --all-databases --disable-compression ``` + +> **Note:** Use the `--all-in-one` or `-A` flag to combine backups into a single file. + --- -## Simple Backup Using Docker Compose +### Simple Restore Using Docker CLI -Below is an example `docker-compose.yml` configuration for running a backup: +To restore a database, bind your local volume to `/backup` and run the `restore` command: + +```shell +docker run --rm --network your_network_name \ + -v $PWD/backup:/backup/ \ + -e "DB_HOST=dbhost" \ + -e "DB_PORT=3306" \ + -e "DB_USERNAME=username" \ + -e "DB_PASSWORD=password" \ + jkaninda/mysql-bkup restore -d database_name -f backup_file.sql.gz +``` + +--- + +### Backup with Docker Compose + +Below is an example of a `docker-compose.yml` file for running a one-time backup: ```yaml services: - mysql-bkup: - # In production, lock the image tag to a specific release version. - # Check https://github.com/jkaninda/mysql-bkup/releases for available releases. + pg-bkup: + # In production, pin your image tag to a specific release version instead of `latest`. + # See available releases: https://github.com/jkaninda/mysql-bkup/releases image: jkaninda/mysql-bkup container_name: mysql-bkup command: backup @@ -71,7 +88,6 @@ services: - DB_USERNAME=bar - DB_PASSWORD=password - TZ=Europe/Paris - # Ensure the mysql-bkup container is connected to the same network as your database. networks: - web @@ -81,11 +97,11 @@ networks: --- -## Recurring Backup with Docker +### Recurring Backups with Docker -To schedule recurring backups, use the `--cron-expression` flag: +You can schedule recurring backups using the `--cron-expression` or `-e` flag: -```bash +```shell docker run --rm --network network_name \ -v $PWD/backup:/backup/ \ -e "DB_HOST=hostname" \ @@ -98,9 +114,13 @@ For predefined schedules, refer to the [documentation](https://jkaninda.github.i --- -## Backup Using Kubernetes +## Deploy on Kubernetes -Below is an example Kubernetes `Job` configuration for running a backup: +For Kubernetes, you can deploy `mysql-bkup` as a Job or CronJob. Below are examples for both. + +### Kubernetes Backup Job + +This example defines a one-time backup job: ```yaml apiVersion: batch/v1 @@ -113,8 +133,8 @@ spec: spec: containers: - name: mysql-bkup - # In production, lock the image tag to a specific release version. - # Check https://github.com/jkaninda/mysql-bkup/releases for available releases. + # Pin the image tag to a specific release version in production. + # See available releases: https://github.com/jkaninda/mysql-bkup/releases image: jkaninda/mysql-bkup command: - /bin/sh @@ -128,7 +148,7 @@ spec: - name: DB_HOST value: "mysql" - name: DB_USERNAME - value: "postgres" + value: "user" - name: DB_PASSWORD value: "password" volumeMounts: @@ -137,11 +157,51 @@ spec: volumes: - name: backup hostPath: - path: /home/toto/backup # Directory location on the host - type: Directory # Optional field + path: /home/toto/backup # Directory location on the host + type: Directory # Optional field restartPolicy: Never ``` +### Kubernetes CronJob for Scheduled Backups + +For scheduled backups, use a `CronJob`: + +```yaml +apiVersion: batch/v1 +kind: CronJob +metadata: + name: pg-bkup-cronjob +spec: + schedule: "0 2 * * *" # Runs daily at 2 AM + jobTemplate: + spec: + template: + spec: + containers: + - name: pg-bkup + image: jkaninda/mysql-bkup + command: + - /bin/sh + - -c + - backup -d dbname + env: + - name: DB_HOST + value: "mysql" + - name: DB_USERNAME + value: "user" + - name: DB_PASSWORD + value: "password" + volumeMounts: + - mountPath: /backup + name: backup + volumes: + - name: backup + hostPath: + path: /home/toto/backup + type: Directory + restartPolicy: OnFailure +``` + --- ## Key Notes