Getting Started¶
Install BorgBackup
Before proceeding further, make sure you have BorgBackup installed on your system. It is not bundled with BorgBoi currently.
Read installation methods here: https://borgbackup.readthedocs.io/en/stable/installation.html.
Installation¶
BorgBoi isn't published to PyPI yet, so it is recommended to install it from the GitHub repo with uv.
Additionally, BorgBackup needs to be installed on your system for BorgBoi to work.
Read installation methods here: https://borgbackup.readthedocs.io/en/stable/installation.html.
Provision AWS Resources¶
For BorgBoi to function properly, it requires an S3 bucket and DynamoDB table.
Use the IAC present in the terraform directory to provision these resources on AWS with Terraform or OpenTofu.
Offline Mode Available
If you prefer not to use AWS services, BorgBoi also supports offline mode. See the Offline Mode section below.
Configuring Environment¶
AWS Credentials¶
Before running BorgBoi, make sure the shell BorgBoi runs in has access to AWS credentials with sufficient permissions for the DynamoDB table and S3 bucket.
BorgBoi Environment Variables¶
The following environment variables can be set:
| Name | Description | Required |
|---|---|---|
BORG_NEW_PASSPHRASE |
Passphrase to use for securing any new Borg repositories | Yes |
BORG_PASSPHRASE |
Passphrase to use for accessing any Borg repositories on your system | Yes |
BORG_S3_BUCKET |
Name of the S3 bucket responsible storing Borg repositories | Online mode only |
BORG_DYNAMODB_TABLE |
Name of the DynamoDB table responsible for storing repo metadata | Online mode only |
BORGBOI_OFFLINE |
Set to enable offline mode (no AWS services required) | No |
Offline Mode¶
BorgBoi supports offline mode for users who prefer not to use AWS services or want to use BorgBoi without cloud dependencies.
Enabling Offline Mode¶
You can enable offline mode in two ways:
- Environment Variable: Set
BORGBOI_OFFLINE=1in your environment - Command Flag: Add
--offlineto any BorgBoi command
How Offline Mode Works¶
In offline mode:
- Repository metadata is stored locally in
~/.borgboi/.borgboi_metadata/instead of DynamoDB - No S3 synchronization occurs during backups
- All Borg operations work normally (create, backup, extract, etc.)
- AWS credentials are not required
Offline Mode Limitations¶
- Repository restoration from S3 is not available
- Repository metadata is not shared across systems
- No cloud backup of repository metadata
- The
list-reposcommand is not yet implemented in offline mode
Create a BorgBoi Repo¶
You can now create a Borg repository with the following BorgBoi command:
