Patroni Dashboard

Do you run a Patroni cluster and want to know at a glance which node is the leader, whether replication is healthy, or what changed overnight? Then this dashboard is for you. It shows all of that — and much more:

• live overview of all nodes, replication lag and the cluster history
• switchover, failover and restarts with a click
• database and user management
• Patroni updates with automatic backup and rollback
• notifications via ntfy, Discord, Slack, webhooks or email
• SSO sign-in and two-factor protection for critical actions

Everything is configured in a guided setup in the browser.

Start with Docker Compose

The compose file runs the prebuilt image, so the source tree is not needed on the server.

1. Install Docker Engine and the Docker Compose plugin.

2. Copy docker-compose.yml and .env.example to the server.

3. Copy .env.example to .env and adjust it, for example the port. The .env file is required: without it docker compose up aborts.

4. Start the dashboard:

   docker compose up -d
   

5. Read the one-time setup token from the application logs and open the dashboard at http://<host>:5050:

   docker compose logs patroni-dashboard
   

6. Complete /setup (set up from scratch or import a backup), then restart the dashboard so the newly saved settings become active:

   docker compose restart patroni-dashboard
   

Put the service behind HTTPS before exposing it beyond a trusted network. The application uses host networking so that it can reach Patroni nodes on private or overlay networks. Configure the reverse proxy to the selected PORT.

To update, run docker compose pull && docker compose up -d. Back up the dashboard-data volume; it holds the dashboard's settings.

Setup wizard

The wizard collects:

• the UI language;
• whether a Patroni cluster already exists;
• the SSO provider (OIDC);
• the dashboard database;
• the Patroni nodes with their SSH access;
• the Patroni paths;
• the notification settings.

Every step is checked before you continue. Make sure the SSO provider, the database and the nodes are reachable from the dashboard host.

Moving to another installation

Settings → Export backup writes a password-protected ZIP file with everything the instance needs. This includes its settings and credentials, as well as its events, action log and saved configurations; the metrics history is optional.

To restore it on a new installation, choose Import backup at the very beginning of the setup. Upload the file and enter its password. You can either keep the database from the backup or start with a new SQLite database. History and logs are loaded after the restart.

Setting up a new Patroni cluster

If the setup wizard is answered with "no cluster yet", the dashboard guides you through setting up a cluster on your servers after the first login (beta). It supports:

• 2–5 database servers with PostgreSQL 16, 17 or 18;
• etcd with 1 or 3 members;
• an optional HAProxy and virtual IP;
• a native, Docker or hybrid installation;
• taking over an existing PostgreSQL instance;
• optional firewall, TLS and pgBackRest backups.

Every step is tested and creates a checkpoint that you can return to. The setup runs automatically, step by step or manually. Generated credentials are shown once at the end.

Adding a database server later

For clusters created by this setup: Settings → Patroni nodes → Set up new server. The new server is prepared like the others, clones itself from the current leader and is then added as a node. For other clusters, Add node only registers a server on which Patroni already runs as a cluster member.

Dashboard database

SQLite needs no setup and is fine for a single dashboard instance. Several instances must share one PostgreSQL or MySQL/MariaDB database (MySQL 8+, MariaDB 10.5+); provide an empty database and a user that may create tables in it.

docker-compose.yml contains an optional PostgreSQL container, commented out. To use it:

1. Set the POSTGRES_* values in .env.

2. Uncomment the db service and the pgdata volume.

3. Start it:

   docker compose --profile local-postgres up -d db
   

4. Enter its address and credentials in the setup wizard.