S3Safe: A Lightweight CLI Tool for S3 Backups and Restores

Managing backups and restores for Amazon S3 (or S3-compatible storage) shouldn’t be complicated. That’s where S3Safe comes in—a lightweight, and flexible CLI tool designed to simplify your backup and restore workflows.

🔐 What is S3Safe?

S3Safe is an open-source command-line tool designed for efficient, and flexible backup and restore operations involving Amazon S3 and any S3-compatible storage (e.g., Wasabi, MinIO, etc.). Whether you're backing up application data, logs, or system snapshots, S3Safe offers a clean and intuitive interface to handle these tasks reliably.

🔑 Key Features

✅ Compression Support – Backup with gzip/tar compression to save space.
✅ Flexible Operations – Backup entire directories, single files, or use recursive operations.
✅ Exclusion Patterns – Skip unwanted files during backup.
✅ Docker Support – Run S3Safe in containerized environments.

🚀 Installation

Via Go

go install github.com/jkaninda/s3safe@latest

Via Docker

docker pull jkaninda/s3safe:latest

⚙️ Configuration

Copy .env.example to .env and configure your S3 credentials:

AWS_REGION=us-east-1
AWS_ENDPOINT=https://s3.wasabisys.com  # For S3-compatible storage
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_KEY=your_secret_key
AWS_BUCKET=your_bucket_name
AWS_FORCE_PATH="true"  # Required for path-style URLs
AWS_DISABLE_SSL="false"  # Set "true" for non-HTTPS endpoints

🛠️ Command Overview

Global Options

Option	Description
`--path`, `-p`	Source path (file or directory)
`--dest`, `-d`	Destination path (S3 or local)
`--recursive`, `-r`	Recursively process directories
`--exclude`, `-e`	Comma-separated exclude patterns
`--file`, `-f`	Use a single file instead of a directory
`--ignore-errors`, `-i`	Continue on restore errors
`--env-file`	Custom `.env` file (default: `.env`)
`--bucket`, `-b`	S3 bucket name

Backup Options

Option	Description
`--compress`, `-c`	Compress the backup as `.tar.gz`
`--timestamp`, `-t`	Add a timestamp to the filename

Restore Options

Option	Description
`--decompress`, `-D`	Decompress after download
`--force`	Force overwrite during the restore

💡 Usage Examples

Backup Operations

Backup a directory (compressed with timestamp):

s3safe backup -p ./backups -d /s3path --compress --timestamp

Backup a single file:

s3safe backup --file data.db --dest /s3path/db-backups --compress

Non-compressed recursive backup:

s3safe backup -p ./backups -d /s3path/backups -r

Restore Operations

Restore & decompress a backup:

s3safe restore -p /s3path/backup.tar.gz -d ./restored --decompress

Restore a directory (recursive):

s3safe restore --path /s3path --dest ./restored --recursive

🐳 Running with Docker

There is no need to install Go or manage dependencies locally—just run it in Docker:

Backup with Docker:

docker run --rm --env-file .env \
  -v "./backups:/backups" \
  jkaninda/s3safe:latest \
  backup --path /backups -d s3path --compress

Restore with Docker:

docker run --rm --env-file .env \
  -v "./restored:/restored" \
  jkaninda/s3safe:latest \
  restore --path s3path/backup.tar.gz -d /restored --decompress

🔗 GitHub: https://github.com/jkaninda/s3safe

🚀 Happy Backing Up! 🚀