1 Getting Started - A Step-by-Step Guide

first edited this page 2025-07-07 04:31:44 +00:00

Table of Contents

• Step 1: System Prerequisites
• Step 2: Deploy Cloud Infrastructure
• Step 3: Configure the Script Environment
• Step 4: Configure Server Permissions
• Step 5: Test and Automate

This guide will walk you through the entire process from zero to a fully automated backup.

Step 1: System Prerequisites

Ensure the server where regularbm will run meets the following requirements:

1. OS: A Debian-based Linux distribution (e.g., Debian, Ubuntu).
2. Docker: Docker must be installed and running the Open WebUI container.
3. Permissions: The user executing the script must have permission to run docker commands. You can grant this by adding the user to the docker group:

   sudo usermod -aG docker $USER
   # IMPORTANT: You must log out and log back in for this change to take effect.
   

4. Python: Python 3 and its virtual environment tool must be available.

   sudo apt update
   sudo apt install -y python3-venv
   

Step 2: Deploy Cloud Infrastructure

Use the provided CloudFormation template to create the necessary AWS resources.

1. Navigate to the CloudFormation service in the AWS Console.
2. Click Create stack -> With new resources (standard).
3. Select Template is ready -> Direct input and paste the contents of cloudformation_template.yaml.
4. Follow the prompts, providing a stack name and globally unique names for your S3 buckets.
5. On the final page, acknowledge that CloudFormation will create IAM resources and click Create stack.
6. Wait for the stack status to become CREATE_COMPLETE.

Step 3: Configure the Script Environment

It is highly recommended to run the script in an isolated Python virtual environment.

1. Place the regularbm.py script in its intended directory (e.g., /opt/scripts/regularbm).
2. Navigate to that directory and create the environment:

   cd /opt/scripts/regularbm
   python3 -m venv venv
   

3. Activate the environment and install dependencies:

   source venv/bin/activate
   pip install boto3 lz4
   

Step 4: Configure Server Permissions

Follow the appropriate pattern from the Core Concepts section.

• If using an EC2 instance (Pattern A): Attach the IAM Instance Profile created by CloudFormation (its name is in the stack's "Outputs" tab) to your EC2 instance via the console (Actions > Security > Modify IAM role).
• If using an external server (Pattern B): Manually create a dedicated IAM User with a narrowly scoped policy and place the generated static keys in the ~/.aws/credentials file on the server. Ensure file permissions are set to 600.

Step 5: Test and Automate

1. Run Manually: Perform a test run to ensure everything is configured correctly.

   # Activate the venv if you haven't already
   source /opt/scripts/regularbm/venv/bin/activate
   
   # Run the script with your parameters
   ./regularbm.py --s3-bucket "your-bucket" --s3-region "us-east-1"
   

2. Automate with Cron: Once the manual test succeeds, schedule the job in your crontab (crontab -e). Use absolute paths for everything.

   # Run regularbm backup daily at 09:00 UTC
   0 9 * * * /opt/scripts/regularbm/venv/bin/python /opt/scripts/regularbm/regularbm.py --s3-bucket "your-bucket" --s3-region "us-east-1" >> /var/log/regularbm.log 2>&1
   

1. Project Wiki: regularbm
2. Introduction
3. Core Concepts
   • Pattern A
   • Pattern B
4. Getting Started - A Step-by-Step Guide
   • Step 1: System Prerequisites
   • Step 2: Deploy Cloud Infrastructure
   • Step 3: Configure the Script Environment
   • Step 4: Configure Server Permissions
   • Step 5: Test and Automate
5. Technical Deep Dive
   • The Backup Process
   • Packaging
   • Configuration: Script Arguments
6. Troubleshooting FAQ