DEV Community

Ali Dadmand
Ali Dadmand

Posted on

🐘 One-Click Production-Ready PostgreSQL HA Cluster with Docker, Patroni, and HAProxy

#postgres #docker #cluster #devops

What if you could spin up a full-featured, highly available PostgreSQL cluster — with failover, monitoring, backups, and load balancing — in a single command?

In modern infrastructure, high availability is no longer a luxury. Whether you're running SaaS, fintech, analytics, or internal platforms, PostgreSQL must stay online, fast, and observable — without manual recovery scripts or ops nightmares.

That’s why I built this:
A one-click, production-grade PostgreSQL HA cluster using Patroni, HAProxy, Prometheus, and Docker — fully optimized for scale, observability, and operational simplicity.

✅ What You Get — In One Command

With just one script, you'll launch a cluster that includes:

  • 🔁 Automatic failover with Patroni
  • ⚖️ Load balancing via HAProxy
  • 📈 Monitoring dashboards (Grafana + Prometheus)
  • 💾 Automated backups and performance tuning scripts
  • 🔐 Secure endpoints ready for production hardening
  • 🐳 Docker-based, no system install required

🧠 Why I Built This

Most PostgreSQL HA setups are complex, manual, and poorly documented. I needed:

  • A setup I could run in 15 minutes or less
  • With all the hard parts automated
  • Something I could trust in real production
  • And extensible enough for future growth

This project solves that — clean, documented, and ready for 1M+ users with minimal resources.

⚙️ Technology Stack

Component Purpose
PostgreSQL Core database
Patroni HA manager and failover controller
etcd Distributed consensus store
HAProxy Load balancer for read/write routing
Prometheus Time-series metrics collection
Grafana Dashboards and alerting

🚀 How to Launch It (One Click Setup)

Requirements

  • Docker + Docker Compose
  • At least 4GB RAM
  • No conflicting services on ports: 5432, 5433, 3000, 7001, 9090

Setup Command 

git clone https://github.com/dadmand/postgres-ha-cluster.git
cd postgres-ha-cluster
chmod +x setup_with_monitoring.sh
./setup_with_monitoring.sh
Enter fullscreen mode Exit fullscreen mode

Within minutes, you'll have a fully running HA PostgreSQL stack on your local machine or cloud instance.

🔐 Secure Endpoints

Role URL/Port Notes
PostgreSQL RW localhost:5432 via HAProxy
PostgreSQL Read localhost:5433 direct read replica access
Grafana localhost:3000 Dashboards (user: admin)
Prometheus localhost:9090 Metrics browser
HAProxy Stats localhost:7001 Load balancer monitoring

⚡ Optimized for Production

PostgreSQL Tuning 

max_connections: 2000
shared_buffers: 1GB
work_mem: 4MB
checkpoint_completion_target: 0.9
autovacuum_max_workers: 3
Enter fullscreen mode Exit fullscreen mode

Lightweight Resource Allocation

Service RAM CPU
PostgreSQL 1GB 2
etcd 256MB 0.5
HAProxy 128MB 0.25
Prometheus 512MB 1
Grafana 256MB 0.5

Total: ~4GB RAM and 8 CPU cores
Tested on macOS, Linux, and cloud VMs.

📈 Observability & Alerting

Grafana comes pre-configured with dashboards for:

  • 🧠 PostgreSQL performance (connections, slow queries, cache hit ratio)
  • ⚙️ Replication status and lag
  • 📊 HAProxy traffic metrics
  • 💻 System resource usage (CPU, RAM, Disk)

Pre-defined alerting thresholds (e.g., replication lag > 10s, disk usage > 85%) are easy to modify in Grafana.

🔄 Backups and Recovery

Manual Backup: 

./config/backup.sh
Enter fullscreen mode Exit fullscreen mode

Simulate Failover: 

docker compose stop patroni1
docker compose exec patroni2 patronictl list
Enter fullscreen mode Exit fullscreen mode

Reset Cluster: 

docker compose down -v
./setup_with_monitoring.sh
Enter fullscreen mode Exit fullscreen mode

🔒 Secure by Default — Hardening Checklist

Before going live in production:

  • [ ] Change default passwords
  • [ ] Configure SSL/TLS for DB and dashboards
  • [ ] Set up firewall rules for ports 5432/3000/7001
  • [ ] Encrypt backup storage
  • [ ] Enable alert channels in Grafana (Slack, email, etc.)
  • [ ] Integrate with your CI/CD pipeline

🔚 Why This Matters

You shouldn’t need a DevOps team just to run PostgreSQL with high availability.

This project gives you a one-click entry point into resilient, observable PostgreSQL — whether you're a solo developer, startup founder, or architect rolling out infrastructure at scale.

📦 Get the Code

🔗 GitHub Repo:
github.com/dadmand/postgres-ha-cluster

📜 License: Apache 2.0
🧠 Designed & maintained by Ali Dadmand

🙌 Like This?

Give it a ⭐ on GitHub
Share it with your team
Or fork it for your own production rollout

Top comments (0)