171 lines
4.2 KiB
Markdown
171 lines
4.2 KiB
Markdown
# Beekeeper
|
|
|
|
Automated Docker volume backup service with compression and FTP upload.
|
|
|
|
## Overview
|
|
|
|
Beekeeper is a Rust-based service that automatically backs up Docker volumes on a scheduled basis. It safely stops containers, compresses their volumes, restarts the containers, and uploads the backups to an FTP server.
|
|
|
|
## Features
|
|
|
|
- **Automated Backups**: Schedule backups using cron expressions
|
|
- **Safe Container Management**: Automatically stops and restarts containers during backup
|
|
- **Efficient Compression**: Creates tar.xz archives for optimal storage
|
|
- **FTP Upload**: Automatically uploads backups to a remote FTP server
|
|
- **Label-Based Selection**: Uses Docker labels to identify containers to backup
|
|
- **Volume Mounting**: Shares the same volumes as the target containers
|
|
|
|
## How It Works
|
|
|
|
1. **Discovery**: Beekeeper scans for Docker containers with the backup label
|
|
2. **Preparation**: Stops the identified containers gracefully
|
|
3. **Compression**: Creates a tar.xz archive of the volume contents
|
|
4. **Restoration**: Restarts the stopped containers
|
|
5. **Upload**: Transfers the backup archive to the configured FTP server
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Description | Required | Example |
|
|
|----------|-------------|----------|---------|
|
|
| `BACKUP_FOLDER` | Path to the folder containing volumes to backup | Yes | `/data/volumes` |
|
|
| `BACKUP_CRON` | Cron expression for backup schedule | Yes | `0 2 * * *` |
|
|
| `FTP_HOST` | FTP server hostname | Yes | `ftp.example.com` |
|
|
| `FTP_PORT` | FTP server port | No | `21` (default) |
|
|
| `FTP_USER` | FTP username | Yes | `backup_user` |
|
|
| `FTP_PASSWORD` | FTP password | Yes | `secret123` |
|
|
| `FTP_PATH` | Remote path on FTP server | No | `/backups` |
|
|
|
|
### Docker Labels
|
|
|
|
Add the following label to containers you want to backup:
|
|
|
|
```yaml
|
|
labels:
|
|
- "beekeeper.backup=true"
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Docker Compose Example
|
|
|
|
```yaml
|
|
version: '3.8'
|
|
|
|
services:
|
|
beekeeper:
|
|
image: beekeeper:latest
|
|
container_name: beekeeper
|
|
privileged: true
|
|
volumes:
|
|
- /var/run/docker.sock:/var/run/docker.sock
|
|
- data-volume:/data/volumes
|
|
environment:
|
|
- BACKUP_FOLDER=/data/volumes
|
|
- BACKUP_CRON=0 2 * * *
|
|
- FTP_HOST=ftp.example.com
|
|
- FTP_USER=backup_user
|
|
- FTP_PASSWORD=secret123
|
|
restart: unless-stopped
|
|
|
|
# Example service to backup
|
|
myapp:
|
|
image: myapp:latest
|
|
volumes:
|
|
- data-volume:/app/data
|
|
labels:
|
|
- "beekeeper.backup=true"
|
|
restart: unless-stopped
|
|
|
|
volumes:
|
|
data-volume:
|
|
```
|
|
|
|
### Standalone Docker
|
|
|
|
```bash
|
|
docker run -d \
|
|
--name beekeeper \
|
|
--privileged \
|
|
-v /var/run/docker.sock:/var/run/docker.sock \
|
|
-v data-volume:/data/volumes \
|
|
-e BACKUP_FOLDER=/data/volumes \
|
|
-e BACKUP_CRON="0 2 * * *" \
|
|
-e FTP_HOST=ftp.example.com \
|
|
-e FTP_USER=backup_user \
|
|
-e FTP_PASSWORD=secret123 \
|
|
beekeeper:latest
|
|
```
|
|
|
|
## Cron Expression Examples
|
|
|
|
| Expression | Description |
|
|
|------------|-------------|
|
|
| `0 2 * * *` | Daily at 2:00 AM |
|
|
| `0 */6 * * *` | Every 6 hours |
|
|
| `0 0 * * 0` | Weekly on Sunday at midnight |
|
|
| `0 3 1 * *` | Monthly on the 1st at 3:00 AM |
|
|
|
|
## Development
|
|
|
|
### Prerequisites
|
|
|
|
- Rust 1.70+
|
|
- Docker 20.10+
|
|
- Docker Compose (optional)
|
|
|
|
### Building
|
|
|
|
```bash
|
|
cargo build --release
|
|
```
|
|
|
|
### Running Locally
|
|
|
|
```bash
|
|
export BACKUP_FOLDER=/tmp/backups
|
|
export BACKUP_CRON="*/5 * * * *"
|
|
export FTP_HOST=localhost
|
|
export FTP_USER=test
|
|
export FTP_PASSWORD=test
|
|
|
|
cargo run
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
cargo test
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
- **Privileged Mode**: Beekeeper requires access to the Docker socket and privileged mode to manage containers
|
|
- **Credentials**: Store FTP credentials securely (use Docker secrets in production)
|
|
- **Network**: Ensure FTP traffic is encrypted (use FTPS if possible)
|
|
- **Permissions**: The backup folder should have appropriate permissions
|
|
|
|
## Limitations
|
|
|
|
- Currently supports FTP only (SFTP/S3 support planned)
|
|
- Containers are stopped during backup (downtime expected)
|
|
- No incremental backup support yet
|
|
|
|
## Roadmap
|
|
|
|
- [ ] SFTP and S3 backend support
|
|
- [ ] Incremental backups
|
|
- [ ] Backup retention policies
|
|
- [ ] Backup verification
|
|
- [ ] Prometheus metrics
|
|
- [ ] Web UI for monitoring
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please open an issue or submit a pull request.
|