diff --git a/bitlab-s3-backup/DOCS.md b/bitlab-s3-backup/DOCS.md new file mode 100755 index 0000000..dcdea7f --- /dev/null +++ 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 diff --git a/bitlab-s3-backup/Dockerfile b/bitlab-s3-backup/Dockerfile new file mode 100755 index 0000000..af0eca3 --- /dev/null +++ b/bitlab-s3-backup/Dockerfile @@ -0,0 +1,41 @@ +ARG BUILD_FROM +FROM ${BUILD_FROM} + +ENV LANG C.UTF-8 + +COPY run.sh / +RUN chmod a+x /run.sh + +# add aws-cli and deps +RUN apk add -v --update --no-cache \ + python3 \ + py3-pip \ + groff \ + less \ + jq \ + aws-cli +#RUN pip3 install --upgrade awscli + +CMD [ "/run.sh" ] + +# Build arugments +ARG BUILD_DATE +ARG BUILD_REF +ARG BUILD_VERSION + +# Labels +LABEL \ + io.hass.name="bitlab S3 backup" \ + io.hass.description="Automatically create and transfer HA backups" \ + io.hass.arch="${BUILD_ARCH}" \ + io.hass.type="addon" \ + io.hass.version=${BUILD_VERSION} \ + maintainer="Alain Stucki