aspian87/mongodb-backup-s3 repository overview

⁠mongodb-backup-s3

This Docker image provides an automated mechanism to back up a MongoDB database to an S3-compatible object storage service. The script (run.sh) performs the following actions:

1. Reads configuration and secrets either from environment variables or from files referenced by _FILE environment variables, as well as from a separate env.sh file.
2. Runs mongodump to create a gzip-compressed archive of your MongoDB database.
3. Uploads the resulting backup archive to an S3 bucket (AWS S3 or S3-compatible endpoint).
4. Optionally cleans up old backups that exceed a specified retention period.

Key Features:

• Automated Scheduled Backups: Use SCHEDULE to run backups at specified cron times.
• On-demand Backups: If SCHEDULE is not set, the container runs one backup and exits.
• Restore Functionality: Restore from the latest or a specified backup timestamp.
• Configurable MongoDB Version: Build with mongo:6.0, mongo:7.0, or mongo:8.0.
• S3-Compatible Storage: AWS, MinIO, or other S3 endpoints supported.
• Backup Retention: Clean up old backups after BACKUP_KEEP_DAYS.
• Multi-Arch Support: Built for linux/amd64 and linux/arm64.

⁠Getting Started

⁠Environment Variables

You can provide configuration via environment variables directly or point them to files containing secrets. The env.sh file is sourced at runtime to centralize configuration defaults. Variables ending with _FILE take precedence if the referenced file is available.

Supported Variables:

⁠Usage

⁠Run Once (No Schedule)

docker run --rm \
  -e MONGODB_HOST="mongo:27017" \
  -e S3_BUCKET="my-s3-bucket" \
  -e AWS_ACCESS_KEY_ID="your_access_key" \
  -e AWS_SECRET_ACCESS_KEY="your_secret_key" \
  aspian87/mongodb-backup-s3:6.0

⁠Scheduled Backups

To run daily at 23:30 on Monday, Wednesday, and Friday (30 23 * * 0,2,4 is UTC-based, adjust as needed):

docker run --rm \
  -e MONGODB_HOST="mongo:27017" \
  -e S3_BUCKET="my-s3-bucket" \
  -e AWS_ACCESS_KEY_ID="your_access_key" \
  -e AWS_SECRET_ACCESS_KEY="your_secret_key" \
  -e SCHEDULE="30 23 * * 0,2,4" \
  aspian87/mongodb-backup-s3:6.0

⁠Restore from Latest Backup

CAUTION: This drops all existing data in MongoDB!

docker exec <container_name> sh restore.sh

If your bucket has more than 1000 backups, the latest may not be the actual latest due to aws s3 ls pagination.

⁠Restore from Specific Backup Timestamp

docker exec <container_name> sh restore.sh 20241012030000

This will download and restore mongodb-backup-20241012030000 from S3.

⁠Using Docker Compose

You can integrate this backup service alongside MongoDB in a docker-compose.yml:

version: "3.9"
services:
  mongo:
    image: mongo:6.0
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: example
    ports:
      - "27017:27017"

  mongodb-backup:
    image: aspian87/mongodb-backup-s3:6.0
    environment:
      MONGODB_HOST: "mongo:27017"
      S3_BUCKET: "my-s3-bucket"
      AWS_ACCESS_KEY_ID: "your_access_key"
      AWS_SECRET_ACCESS_KEY: "your_secret_key"
      # SCHEDULE: "30 23 * * 0,2,4" # Example schedule
      BACKUP_KEEP_DAYS: "14"
    depends_on:
      - mongo

Adjust the tag (6.0, 7.0, 8.0) as needed.

⁠Logging

run.sh provides detailed logging to aid debugging:

• Start/End Messages: Indicates the start and end of backup and cleanup processes.
• Warnings/Errors: Warns if expected variables are missing or fallback defaults are used.
• Detailed Steps: Logs each step such as reading secrets, dumping the database, uploading to S3, and cleaning up old backups.

⁠Contributing

Contributions are welcome! Please open an issue or pull request for any improvements, bug fixes, or feature requests.

⁠License

MIT License⁠ - Please see the LICENSE⁠ file for details.