update

2024-04-03 14:44:29 +02:00
parent b0c10539bb
commit 5f76037f34
5 changed files with 264 additions and 0 deletions
--- a/bitlab-s3-backup/DOCS.md
+++ b/bitlab-s3-backup/DOCS.md
@@ -0,0 +1,103 @@
+# Home Assistant Add-on: S3 Backup
+
+## Installation
+
+Follow these steps to get the add-on installed on your system:
+
+1. Enable **Advanced Mode** in your Home Assistant user profile.
+2. Navigate in your Home Assistant frontend to **Supervisor** -> **Add-on Store**.
+3. Search for "Amazon S3 Backup" add-on and click on it.
+4. Click on the "INSTALL" button.
+
+## How to use
+
+1. Set the `aws_access_key`, `aws_secret_access_key`, and `bucket_name`.
+2. Optionally / if necessary, change `bucket_region`, and `delete_local_backups` and `local_backups_to_keep` configuration options.
+3. Start the add-on to sync the `/backup/` directory to the configured `bucket_name` on Amazon S3. You can also automate this of course, see example below:
+
+## Automation
+
+To automate your backup creation and syncing to Amazon S3, add these two automations in Home Assistants `configuration.yaml` and change it to your needs:
+```
+automation:
+  # create a full backup
+  - id: bitlab-backup
+    alias: Create a full backup every day at 4am
+    trigger:
+      platform: time
+      at: "04:00:00"
+    action:
+      service: hassio.addon_start
+      addon: XXXXX_bitlab-s3-backup
+    
+```
+
+The automation above first creates a full backup at 4am, and then at 4:15am syncs to Amazon S3 and if configured deletes local backups according to your configuration.
+
+## Configuration
+
+Example add-on configuration:
+
+```
+aws_access_key: AKXXXXXXXXXXXXXXXX
+aws_secret_access_key: XXXXXXXXXXXXXXXX
+bucket_name: my-bucket
+bucket_region: minio
+delete_local_backups: true
+local_backups_to_keep: 3
+```
+
+### Option: `aws_access_key` (required)
+AWS IAM access key used to access the S3 bucket.
+
+### Option: `aws_secret_access_key` (required)
+AWS IAM secret access key used to access the S3 bucket.
+
+### Option: `bucket_name` (required)
+Amazon S3 bucket used to store backups.
+
+### Option: `bucket_region` (optional, Default: eu-central-1)
+AWS region where the S3 bucket was created. See https://aws.amazon.com/about-aws/global-infrastructure/ for all available regions.
+
+### Option: `delete_local_backups` (optional, Default: true)
+Should the addon remove oldest local backups after syncing to your Amazon S3 Bucket? You can configure how many local backups you want to keep with the Option `local_backups_to_keep`. Oldest Backups will get deleted first.
+
+### Option: `local_backups_to_keep` (optional, Default: 3)
+How many backups you want to keep locally? If you want to disable automatic local cleanup, set `delete_local_backups` to false.
+
+If you also want to automatically delete backups to keep your Amazon S3 Bucket clean, or change the storage class for backups to safe some money, you should take a look at S3 Lifecycle Rules (https://docs.aws.amazon.com/AmazonS3/latest/userguide/how-to-set-lifecycle-configuration-intro.html).
+
+## Security
+I recommend to create a new IAM user, which:
+- can not login to the AWS Console
+- can only access AWS programmatically
+- is used by this add-on only
+- uses the lowest possible IAM Policy, which is this:
+
+```
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Sid": "AllowAWSS3Sync",
+            "Effect": "Allow",
+            "Action": [
+                "s3:PutObject",
+                "s3:ListBucket"
+            ],
+            "Resource": [
+                "arn:aws:s3:::YOUR-S3-BUCKET-NAME/*",
+                "arn:aws:s3:::YOUR-S3-BUCKET-NAME"
+            ]
+        }
+    ]
+}
+```
+
+## Support
+
+Usage of the addon requires knowledge of Amazon S3 and AWS IAM.
+Under the hood it uses the aws cli version 1, specifically the `aws s3 sync` command.
+
+## Thanks
+This addon is highly inspired by https://github.com/gdrapp/hass-addons and https://github.com/rrostt/hassio-backup-s3