# 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 S3Saf[e?](https://github.com/jkaninda/s3safe)

[S3Safe](https://github.com/jkaninda/s3safe) is an open[\-sourc](https://github.com/jkaninda/s3safe)e 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

```sh
go install github.com/jkaninda/s3safe@latest
```

### Via Docker

```sh
docker pull jkaninda/s3safe:latest
```

## ⚙️ Configuration

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

```ini
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):**

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

**Backup a single file:**

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

**Non-compressed recursive backup:**

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

### **Restore Operations**

**Restore & decompress a backup:**

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

**Restore a directory (recursive):**

```sh
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:**

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

**Restore with Docker:**

```sh
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](https://github.com/jkaninda/s3safe)

🚀 **Happy Backing Up!** 🚀