S3Safe: A Lightweight CLI Tool for S3 Backups and Restores
I'm a Software Engineer passionate about building scalable systems and simplifying infrastructure through open source. With over 5 years of hands-on experience, I specialize in Go (Golang), Kotlin, Spring Boot, and Linux-based systems, with a strong DevOps foundation in Docker, Kubernetes, and CI/CD automation.
I'm the author of several open source tools, including:
- PG-BKUP – PostgreSQL backup and restore
- MYSQL-BKUP – MySQL backup and restore solution
- Goma Gateway – Declarative API Gateway and reverse proxy
- Okapi – Fast and extensible web framework in Go
My focus is on building developer-friendly tools that are lightweight, portable, and production-ready.
Areas of Focus:
- Cloud-native architecture & API design
- Developer tooling & platform engineering
- DevOps, GitOps, and SRE best practices
- Secure infrastructure & automation workflows
Open source is at the core of my work. I thrive in both independent and collaborative environments, always aiming for clean code, thoughtful design, and real-world impact.
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! 🚀
