🐘 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

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

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

Simulate Failover:

docker compose stop patroni1
docker compose exec patroni2 patronictl list

Reset Cluster:

docker compose down -v
./setup_with_monitoring.sh

🔒 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.