{"id":28496306,"url":"https://github.com/lafayettegabe/wald","last_synced_at":"2025-07-02T15:30:38.519Z","repository":{"id":296935578,"uuid":"995075324","full_name":"lafayettegabe/wald","owner":"lafayettegabe","description":"🐘 PostgreSQL docker image with automated WAL-G backups to S3. Enterprise-grade backup solution. Zero-configuration, production-ready.","archived":false,"fork":false,"pushed_at":"2025-06-03T20:08:45.000Z","size":24,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-04T05:09:08.085Z","etag":null,"topics":["backups","database","database-backup","docker","postgres","postgresql","wal-g","wald"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/repository/docker/lafayettegabe/wald","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lafayettegabe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-02T23:46:12.000Z","updated_at":"2025-06-03T21:12:47.000Z","dependencies_parsed_at":"2025-06-04T05:09:11.148Z","dependency_job_id":null,"html_url":"https://github.com/lafayettegabe/wald","commit_stats":null,"previous_names":["lafayettegabe/docker-postgres-walg","lafayettegabe/wald"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/lafayettegabe/wald","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lafayettegabe%2Fwald","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lafayettegabe%2Fwald/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lafayettegabe%2Fwald/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lafayettegabe%2Fwald/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lafayettegabe","download_url":"https://codeload.github.com/lafayettegabe/wald/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lafayettegabe%2Fwald/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263165657,"owners_count":23423986,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backups","database","database-backup","docker","postgres","postgresql","wal-g","wald"],"created_at":"2025-06-08T12:07:15.009Z","updated_at":"2025-07-02T15:30:38.454Z","avatar_url":"https://github.com/lafayettegabe.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐘 PostgreSQL + WAL-G Docker Image\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.docker.com/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Docker-2496ED?style=for-the-badge\u0026logo=docker\u0026logoColor=white\" alt=\"Docker\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.postgresql.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/PostgreSQL-316192?style=for-the-badge\u0026logo=postgresql\u0026logoColor=white\" alt=\"PostgreSQL\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://aws.amazon.com/s3/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Amazon_AWS-FF9900?style=for-the-badge\u0026logo=amazonaws\u0026logoColor=white\" alt=\"AWS S3\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.linux.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Linux-FCC624?style=for-the-badge\u0026logo=linux\u0026logoColor=black\" alt=\"Linux\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.gnu.org/software/bash/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Shell_Script-121011?style=for-the-badge\u0026logo=gnu-bash\u0026logoColor=white\" alt=\"Shell Script\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/lafayettegabe/wald\"\u003e\u003cimg src=\"https://img.shields.io/badge/Multi--Architecture-AMD64%20%7C%20ARM64-blue?style=flat-square\" alt=\"Multi-Architecture\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/lafayettegabe/wald\"\u003e\u003cimg src=\"https://img.shields.io/badge/Automated-Backups-green?style=flat-square\" alt=\"Automated Backups\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/lafayettegabe/wald\"\u003e\u003cimg src=\"https://img.shields.io/badge/S3-Compatible-orange?style=flat-square\" alt=\"S3 Compatible\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/lafayettegabe/wald\"\u003e\u003cimg src=\"https://img.shields.io/badge/Email-Notifications-purple?style=flat-square\" alt=\"Email Notifications\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003e 🚀 **Production-ready PostgreSQL with automated WAL-G backups to S3-compatible storage**\n\nA Docker image that combines PostgreSQL with WAL-G for automated, encrypted backups to S3-compatible storage. Features include automatic WAL archiving, scheduled incremental and full backups, intelligent cleanup, and email notifications.\n\n## ✨ Features\n\n- 🔄 **Automated Backup Scheduling**\n  - Incremental backups every 2 hours\n  - Full backups daily at 4 AM\n  - Automated cleanup daily at 5 AM\n- 🏗️ **Multi-Architecture Support** - AMD64 and ARM64\n- 🔐 **Encryption** - Built-in libsodium encryption\n- 📧 **Email Notifications** - Success/failure notifications\n- 🗄️ **S3-Compatible Storage** - AWS S3, MinIO, etc.\n- 📊 **Comprehensive Logging** - Detailed backup logs\n- ⚡ **Optimized Performance** - Tuned PostgreSQL parameters\n- 🔧 **Zero Configuration** - Works out of the box\n\n## 🚀 Quick Start\n\n### 1. Create Environment File\n\nCreate a `.env` file with your configuration:\n\n```bash\n# PostgreSQL Configuration\nPOSTGRES_DB=myapp\nPOSTGRES_USER=postgres\nPOSTGRES_PASSWORD=secure_password\n\n# AWS/S3 Configuration\nAWS_ACCESS_KEY_ID=your_access_key\nAWS_SECRET_ACCESS_KEY=your_secret_key\nAWS_REGION=us-east-1\nWALG_S3_PREFIX=s3://your-bucket/postgres-backups\n\n# WAL-G Configuration\nWALG_LIBSODIUM_KEY=your_64_character_hex_encryption_key_here_1234567890abcdef\nWALG_RETENTION_DAYS=30\n\n# Optional: Custom S3 Endpoint (for MinIO, etc.)\n# AWS_ENDPOINT=https://your-minio-endpoint.com\n\n# Optional: Email Notifications\n# WALG_NOTIFICATION_EMAIL=admin@yourcompany.com\n```\n\n### 2. Run with Docker Compose\n\n```yaml\nservices:\n  postgres:\n    image: lafayettegabe/wald:latest\n    container_name: postgres-walg\n    restart: unless-stopped\n    ports:\n      - \"5432:5432\"\n    env_file:\n      - .env\n    volumes:\n      - ./data/postgres:/var/lib/postgresql/data\n      - ./data/logs:/var/log/wal-g\n```\n\n```bash\ndocker-compose up -d\n```\n\n### 3. Verify Backup Setup\n\n```bash\n# Check container logs\ndocker logs postgres-walg\n\n# Check backup status\ndocker exec postgres-walg su - postgres -c \"envdir /etc/wal-g/env /usr/local/bin/wal-g backup-list\"\n\n# View backup logs\ndocker exec postgres-walg tail -f /var/log/wal-g/backup-cron.log\n```\n\n## 📋 Environment Variables\n\n### Required Variables\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `AWS_ACCESS_KEY_ID` | AWS/S3 access key | `AKIAIOSFODNN7EXAMPLE` |\n| `AWS_SECRET_ACCESS_KEY` | AWS/S3 secret key | `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` |\n| `WALG_S3_PREFIX` | S3 backup location | `s3://my-bucket/postgres-backups` |\n| `WALG_LIBSODIUM_KEY` | 64-char hex encryption key | `64_character_hex_string_here...` |\n\n### Optional Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `AWS_REGION` | `us-east-1` | AWS region |\n| `AWS_ENDPOINT` | - | Custom S3 endpoint (MinIO, etc.) |\n| `WALG_RETENTION_DAYS` | `30` | Backup retention period |\n| `WALG_COMPRESSION_METHOD` | `lz4` | Compression method |\n| `WALG_AUTOMATED_BACKUPS` | `true` | Enable/disable automated backups |\n| `WALG_NOTIFICATION_EMAIL` | - | Email for backup notifications |\n| `WALG_UPLOAD_CONCURRENCY` | `16` | Upload concurrency |\n| `WALG_DOWNLOAD_CONCURRENCY` | `10` | Download concurrency |\n\n## 🕒 Backup Schedule\n\nThe backup schedule is **hardcoded** for reliability and cannot be changed via environment variables:\n\n| Type | Schedule | Description |\n|------|----------|-------------|\n| **Incremental** | `0 */2 * * *` | Every 2 hours |\n| **Full Backup** | `0 4 * * *` | Daily at 4:00 AM |\n| **Cleanup** | `0 5 * * *` | Daily at 5:00 AM |\n\n## 🛠️ Manual Operations\n\n### Create Manual Backup\n\n```bash\n# Full backup\ndocker exec postgres-walg su - postgres -c \"WALG_DELTA_MAX_STEPS=0 envdir /etc/wal-g/env /usr/local/bin/wal-g backup-push /var/lib/postgresql/data\"\n\n# Incremental backup\ndocker exec postgres-walg su - postgres -c \"envdir /etc/wal-g/env /usr/local/bin/wal-g backup-push /var/lib/postgresql/data\"\n```\n\n### List Backups\n\n```bash\n# Simple list\ndocker exec postgres-walg su - postgres -c \"envdir /etc/wal-g/env /usr/local/bin/wal-g backup-list\"\n\n# Detailed view\ndocker exec postgres-walg su - postgres -c \"envdir /etc/wal-g/env /usr/local/bin/wal-g backup-list --detail\"\n```\n\n### Restore Database\n\n```bash\n# Stop the container\ndocker-compose down\n\n# Remove existing data\nsudo rm -rf ./data/postgres/*\n\n# Restore from latest backup\ndocker run --rm \\\n  --env-file .env \\\n  -v $(pwd)/data/postgres:/var/lib/postgresql/data \\\n  lafayettegabe/wald:latest \\\n  su - postgres -c \"envdir /etc/wal-g/env /usr/local/bin/wal-g backup-fetch /var/lib/postgresql/data LATEST\"\n\n# Start container\ndocker-compose up -d\n```\n\n### Point-in-Time Recovery\n\n```bash\n# Restore to specific time\ndocker run --rm \\\n  --env-file .env \\\n  -v $(pwd)/data/postgres:/var/lib/postgresql/data \\\n  lafayettegabe/wald:latest \\\n  su - postgres -c \"envdir /etc/wal-g/env /usr/local/bin/wal-g backup-fetch /var/lib/postgresql/data LATEST\"\n\n# Create recovery configuration\necho \"restore_command = 'envdir /etc/wal-g/env /usr/local/bin/wal-g wal-fetch %f %p'\" \u003e ./data/postgres/recovery.conf\necho \"recovery_target_time = '2025-06-02 14:30:00'\" \u003e\u003e ./data/postgres/recovery.conf\n```\n\n## 📊 Monitoring \u0026 Logs\n\n### Log Locations\n\n| Log Type | Location | Description |\n|----------|----------|-------------|\n| **WAL Archive** | `/var/log/wal-g/archive.log` | WAL file archiving |\n| **Backup Cron** | `/var/log/wal-g/backup-cron.log` | Scheduled backups |\n| **Cleanup** | `/var/log/wal-g/cleanup-cron.log` | Backup cleanup |\n| **Setup** | `/var/log/wal-g/cron-setup.log` | Initial setup |\n\n### View Logs\n\n```bash\n# Real-time backup logs\ndocker exec postgres-walg tail -f /var/log/wal-g/backup-cron.log\n\n# Archive logs\ndocker exec postgres-walg tail -f /var/log/wal-g/archive.log\n\n# All WAL-G logs\ndocker exec postgres-walg tail -f /var/log/wal-g/*.log\n```\n\n### Health Checks\n\n```bash\n# Check PostgreSQL status\ndocker exec postgres-walg pg_isready -U postgres\n\n# Check latest backup\ndocker exec postgres-walg su - postgres -c \"envdir /etc/wal-g/env /usr/local/bin/wal-g backup-list | tail -1\"\n\n# Check disk usage\ndocker exec postgres-walg df -h /var/lib/postgresql/data\n```\n\n## 🔧 Advanced Configuration\n\n### Custom PostgreSQL Parameters\n\nThe image includes optimized PostgreSQL parameters for backup performance:\n\n```ini\narchive_mode = on\narchive_command = /scripts/archive-command.sh '%p' '%f'\narchive_timeout = 300\nwal_level = replica\nmax_wal_senders = 10\nwal_keep_size = 1GB\nwal_compression = on\ncheckpoint_completion_target = 0.7\ncheckpoint_timeout = 15min\nmax_wal_size = 2GB\nmin_wal_size = 1GB\n```\n\n### Encryption Key Generation\n\nGenerate a secure encryption key:\n\n```bash\n# Generate 256-bit key\nopenssl rand -hex 32\n```\n\n### S3 Bucket Policy\n\nExample S3 bucket policy for WAL-G:\n\n```json\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Principal\": {\n        \"AWS\": \"arn:aws:iam::ACCOUNT:user/walg-user\"\n      },\n      \"Action\": [\n        \"s3:GetObject\",\n        \"s3:PutObject\",\n        \"s3:DeleteObject\",\n        \"s3:ListBucket\"\n      ],\n      \"Resource\": [\n        \"arn:aws:s3:::your-bucket/*\",\n        \"arn:aws:s3:::your-bucket\"\n      ]\n    }\n  ]\n}\n```\n\n## 🏗️ Building from Source\n\n### Prerequisites\n\n- Docker with Buildx\n- Multi-architecture builder\n\n### Build Commands\n\n```bash\n# Clone repository\ngit clone https://github.com/lafayettegabe/wald.git\ncd wald\n\n# Build multi-architecture image\nchmod +x build.sh\n./build.sh\n```\n\n### Build Configuration\n\nThe build script creates images for:\n- `linux/amd64` (Intel/AMD 64-bit)\n- `linux/arm64` (ARM 64-bit, Apple Silicon, etc.)\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**Backup Fails with Permission Error**\n```bash\n# Check WAL-G environment permissions\ndocker exec postgres-walg ls -la /etc/wal-g/env/\n```\n\n**WAL Files Not Archiving**\n```bash\n# Check archive command logs\ndocker exec postgres-walg tail -20 /var/log/wal-g/archive.log\n```\n\n**S3 Connection Issues**\n```bash\n# Test S3 connectivity\ndocker exec postgres-walg su - postgres -c \"envdir /etc/wal-g/env /usr/local/bin/wal-g backup-list\"\n```\n\n**Container Won't Start**\n```bash\n# Check required environment variables\ndocker-compose config\n```\n\n### Debug Mode\n\nEnable verbose logging:\n\n```bash\n# Run with debug output\ndocker run -it --env-file .env lafayettegabe/wald:latest bash\n```\n\n## 📚 Documentation\n\n- [PostgreSQL Documentation](https://www.postgresql.org/docs/)\n- [WAL-G Documentation](https://wal-g.readthedocs.io/)\n- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/)\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [WAL-G Team](https://github.com/wal-g/wal-g) for the excellent backup tool\n- [PostgreSQL Community](https://www.postgresql.org/) for the amazing database\n- [Docker Community](https://www.docker.com/) for containerization platform\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e⭐ Star this repo if it helped you! ⭐\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/lafayettegabe/wald/issues\"\u003eReport Bug\u003c/a\u003e •\n  \u003ca href=\"https://github.com/lafayettegabe/wald/issues\"\u003eRequest Feature\u003c/a\u003e •\n  \u003ca href=\"https://github.com/lafayettegabe/wald\"\u003eView Source\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flafayettegabe%2Fwald","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flafayettegabe%2Fwald","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flafayettegabe%2Fwald/lists"}