From 8860c2eb13aeb6bfc9710c838f7f3be57b9b81ba Mon Sep 17 00:00:00 2001
From: Audrey Jensen <ajensen@cramalot.com>
Date: Thu, 3 Apr 2025 08:25:12 -0500
Subject: [PATCH] add readme

---
 readme.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 readme.md

diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..bc351b6
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,109 @@
+# MySQL Automatic Backup
+A sidecar container for backing up MySQL databases.  
+Every night at 23:50, internal cron runs `mysqldump` to dump all databases on the target server to a SQL file.  
+
+## Changing when the job runs
+[mysqlCron](mysqlCron) defines when the job will be run. To change this, simply modify the values. Use the chart below as reference.  
+By default, the job is confirued to run at 23:50 every night. 
+> [!IMPORTANT] 
+> The crontab file (mysqlCron) must always contain an empty line at the end of the file.
+```
+50 23 * * * backup.sh >> /var/log/cron.log 2>&1
+- - - - -
+| | | | |
+| | | | ----- Day of week (0 - 7) (Sunday=0 or 7)
+| | | ------- Month (1 - 12)
+| | --------- Day of month (1 - 31)
+| ----------- Hour (0 - 23)
+------------- Minute (0 - 59)
+```
+# Usage
+Simply start a container using this image. 
+The service needs to have network access to the target server on a network that can log into the target with a root password.
+
+## Install
+It's recommended to set up this container by adding it to the target service's docker compose.
+### Examples
+#### Simple Setup
+```
+version: "3"
+services:
+  db:
+    image: mysql:latest
+    container_name: nasdb
+    restart: always
+    env_file: stack.env
+    volumes:
+      - "db:/var/lib/mysql"
+    networks:
+      - nastest
+  backup:
+    image: gitea.jv.com/audrey/mysql-backup-agent:test
+    env_file: stack.env
+    environment:
+      MYSQL_HOST: nasdb
+      BACKUP_NAME: nastest
+      APPEND_DATE: true
+    networks:
+      - nastest
+volumes:
+  db:
+    driver: local
+  backup:
+    driver: local
+networks:
+  nastest:
+    external: false
+```
+#### Backup to NAS
+For increased data security, it's recommended to store database backups on the NAS where they can take advantage of increased storage, automatic snapshots, & further backups.
+> [!IMPORTANT]
+> If you intend to keep regular snapshots of this backup on the file server, you should set APPEND_DATE to false 
+```
+version: "3"
+services:
+  db:
+    image: mysql:latest
+    container_name: nasdb
+    restart: always
+    env_file: stack.env
+    volumes:
+      - "db:/var/lib/mysql"
+    networks:
+      - nastest
+  backup:
+    image: gitea.jv.com/audrey/mysql-backup-agent:test
+    env_file: stack.env
+    environment:
+      MYSQL_HOST: nasdb
+      BACKUP_NAME: nastest
+      APPEND_DATE: false
+    networks:
+      - nastest
+volumes:
+  db:
+    driver: local
+  backup:
+    driver: local
+    driver_opts: #config to connect to an NFS share is defined using these options
+      type: nfs
+      o: addr=172.16.1.2,rw #If a direct link is available, use that
+      device: :/mnt/tank/Docker/Volumes/Intranet #this will usually be the path to the folder shared by NFS, relative to the file server.
+networks:
+  nastest:
+    external: false
+```
+## Config
+Some basic config options are available through environment variables.
+### Required Vars
+
+| Variable | Description | Example |
+| :--- | :--- | :--- |
+| MYSQL_HOST | The IP/identifier of the target server. Typically, the container name or ID | `MYSQL_HOST=websitedb` |
+| MYSQL_ROOT_PASSWORD | The root password of the target server. Used for authentication | `MYSQL_ROOT_PASSWORD=someval` |
+#### Optional Vars
+
+|Variable|Description|Example|
+| :--- | :--- | :---|
+|APPEND_DATE|`Default: false` If set, appends the yyyy-mm-dd of the backup to the end of the file name. Leaving this unset will cause existing backups to be overwritten.| `APPEND_DATE=true`|
+|BACKUP_NAME|`Default: Value of MYSQL_HOST`If set, the name of the file will be set to this value. Example: setting this to 'epicdb' will cause  files to save as 'epicdb.sql'|`BACKUP_NAME='pubweb-backup'`|