Installation Guide for Patroni-Based HA Deployment
Patroni-based High Availability keeps ServiceOps running without interruption. Even when a server fails, ServiceOps automatically promotes a standby database to primary and reroutes all traffic through HAProxy without manual intervention.
This guide covers Patroni and ETCD-based HA configuration for ServiceOps. Use it when your environment uses Patroni-based installer packages. Two deployment layouts are covered: a 3-machine standalone setup where the application and database share each node, and a 5-machine distributed setup where application and database run on separate dedicated machines.
This guide covers:
- How Does Patroni-Based High Availability Work?
- Standalone HA Deployment (3 Machines)
- Distributed HA Deployment (5 Machines)
- Best Practices
- Back up your database before starting any HA configuration step if you are working on an existing production environment. See the ServiceOps Application and Database Backup Procedure.
- Back up your HAProxy configuration on the Observer machine from
/etc/haproxybefore making any changes.
This setup supports the following OS and PostgreSQL versions only:
- OS: Ubuntu 22, Ubuntu 24, RHEL 9.4, RHEL 9.6
- PostgreSQL: Version 16 or Version 17
How Does Patroni-Based High Availability Work?
Patroni manages the PostgreSQL Leader/Replica relationship between the Master and Slave database nodes. ETCD stores the cluster state and runs leader election. When the Master database fails, Patroni reads ETCD, promotes the Replica to Leader, and updates the cluster state automatically. HAProxy routes all database traffic to the current Patroni Leader using a health check on port 8008. The Application Observer monitors the application tier separately and triggers failover scripts when it detects the Master application is unreachable. All nodes must communicate with each other over the network for this coordination to work.
Standalone HA Deployment (3 Machines)
In this layout, each application node co-locates the ServiceOps application and the PostgreSQL database on the same server. The Observer node runs HAProxy, ETCD, and the Application Observer.
Prerequisites
Before starting, confirm the following:
- Operating System: Ubuntu 22, Ubuntu 24, RHEL 9.4, or RHEL 9.6
- PostgreSQL Version: 16 or 17
- 3 machines provisioned and reachable over the network
- ServiceOps installed on both APP + DB Node 1 and APP + DB Node 2 (follow the Standalone Installation Guide)
- Root or sudo access on all 3 machines
- Setup scripts extracted on their respective machines:
MotadataETCDSetupU24on the Observer machineMotadataPatroniSetupU24on both APP + DB machinesMotadataAppHASetupon the Observer machine
- Firewall ports open on each machine:
| Machine | Open Ports |
|---|---|
| Observer | 80 (Optional), 443, 2379, 2380, 5000, 7000 |
| APP + DB Node 1 and Node 2 | 80 (Optional), 443, 5432, 8008 |
Architecture Overview

The 3-machine standalone layout assigns the following roles:
| Role | Description | Example IP |
|---|---|---|
| Observer / HAProxy / ETCD | Manages load balancing, cluster coordination, and failover | 172.16.13.42 |
| APP + DB Node 1 (Master) | Runs the active ServiceOps application and the Patroni Leader database | 172.16.12.171 |
| APP + DB Node 2 (Slave) | Runs the standby ServiceOps application and the Patroni Replica database | 172.16.12.177 |
Components and Roles
- Observer Node (HA Proxy/ETCD/Application Observer): Acts as the single entry point for all client traffic (Agents, Technicians, Requesters). HAProxy load-balances application traffic on ports
80(optional) and443, and routes database connections to the Patroni Leader through port5000and7000. ETCD (ports2379/2380) stores cluster state, maintains distributed consensus, and coordinates Patroni leader election. The Application Observer monitors both servers and triggers failover scripts when the Master becomes unavailable. - Master Server (ServiceOps App Primary + Patroni Leader Database): Active server handling all live application requests. The ServiceOps application connects to the co-located Patroni Leader database via localhost. Accessible from the Observer on ports
80(optional) and443; Patroni communicates on ports5432, and8008. - Slave Server (ServiceOps App Standby + Patroni Replica/Standby Database): Passive standby server kept in continuous sync with the Master and promoted automatically on failure. The ServiceOps application connects to the co-located Patroni Replica database via localhost. Port profile:
80/443for application traffic;5432, and8008for Patroni. - Patroni: Manages PostgreSQL high availability on both nodes. Continuously replicates the database from the Master (Leader) to the Slave (Replica) and automatically promotes the Slave to Leader if the Master fails.
- ETCD: Distributed key-value store used for cluster coordination, service discovery, and Patroni leader election between the Observer and both servers.
- File DB Sync: Synchronizes non-database files (attachments, patches, packages, logs) bidirectionally between Master and Slave, ensuring file-level consistency across both nodes.
Procedure
Step 1: Download Setup Files
Download the zip file containing all setup files from the Download Links page and extract it on all three machines before proceeding.
Step 2: Set Up the Observer (ETCD and HAProxy)
Run the following steps on the Observer machine (172.16.13.42).
Give
MotadataETCDSetupU24execute permissions and run it:chmod 777 MotadataETCDSetupU24
./MotadataETCDSetupU24
Type
yeswhen prompted to install and configure ETCD.
Enter
1when prompted for the ETCD node number. This setup uses a single ETCD node.Maximum ETCD Cluster NodesThis setup supports a maximum of 7 ETCD cluster nodes. Leave all additional node prompts blank for a single-node setup.

Leave all additional ETCD node prompts blank and press Enter.

Type
yeswhen prompted to install and configure HAProxy.
Enter the DB and APP IP addresses when prompted:
Prompt Value DB Node 1 IP 172.16.12.171DB Node 2 IP 172.16.12.177APP Node 1 IP 172.16.12.171APP Node 2 IP 172.16.12.177
ETCD and HAProxy setup is complete.
Verify the HAProxy Configuration
Open /etc/haproxy/haproxy.cfg and confirm it matches this structure:
global
maxconn 100
defaults
log global
mode tcp
retries 2
timeout client 30m
timeout connect 4s
timeout server 30m
timeout check 5s
listen stats
mode http
bind *:7000
stats enable
stats uri /
listen postgres
bind *:5000
option httpchk
http-check expect status 200
default-server inter 3s fall 3 rise 2 on-marked-down shutdown-sessions
server etcd1 172.16.12.171:5432 maxconn 100 check port 8008
server etcd2 172.16.12.177:5432 maxconn 100 check port 8008
listen backend
bind *:80
balance roundrobin
mode tcp
option tcp-check
server ubuntu1 172.16.12.171:80 check port 80
server ubuntu2 172.16.12.177:80 check port 80
Verify ETCD Service Status
Check that the ETCD service is running before continuing:
systemctl status motadata_etcd
If the service is inactive, start it:
systemctl start motadata_etcd
Step 3: Configure the Master Database
Run the following steps on APP + DB Node 1 / Master (172.16.12.171).
Give
MotadataPatroniSetupU24execute permissions and run it:chmod 777 MotadataPatroniSetupU24
./MotadataPatroniSetupU24Enter
1when prompted to select Node 1 or Node 2.Enter the Slave IP address when prompted:
172.16.12.177.
Enter the ETCD IP address when prompted:
172.16.13.42.
Patroni setup on the Master node is complete.
Step 4: Configure the Slave Database
Run the following steps on APP + DB Node 2 / Slave (172.16.12.177).
- Give
MotadataPatroniSetupU24execute permissions and run it:chmod 777 MotadataPatroniSetupU24
./MotadataPatroniSetupU24 - Enter
2when prompted to select Node 1 or Node 2. - Enter the Master IP address when prompted:
172.16.12.171. - Enter the ETCD IP address when prompted:
172.16.13.42.
After setup, confirm the Patroni service on the Slave is inactive. If it shows active or running, stop it:
systemctl stop patroni
Do not continue to Step 5 until the Slave Patroni service is inactive.

Step 5: Configure the Master Application
Run the following steps on APP + DB Node 1 / Master (172.16.12.171).
Copy
MotadataPatroniHAMasterSlaveAppConfigfrom the Master/opt/HAfolder to the home directory.Give it execute permissions and run it:
chmod 777 MotadataPatroniHAMasterSlaveAppConfig
./MotadataPatroniHAMasterSlaveAppConfigEnter the Observer IP address when prompted:
172.16.13.42.
Enter
masterwhen asked for the machine role.
Master application configuration is complete.

Step 6: Configure the Slave Application
Run the following steps on APP + DB Node 2 / Slave (172.16.12.177).
Copy
MotadataPatroniHAMasterSlaveAppConfigfrom the Master/opt/HAfolder to the home directory on the Slave.Give it execute permissions and run it:
chmod 777 MotadataPatroniHAMasterSlaveAppConfig
./MotadataPatroniHAMasterSlaveAppConfigEnter the Observer IP address when prompted:
172.16.13.42.Enter
slavewhen asked for the machine role.
Enter the Master application's DB password when prompted.

Copy the DB password directly from the Master. The password must be identical on both nodes.
Slave application configuration is complete.
Step 7: Run DB Configuration on the Master
Run the following steps on APP + DB Node 1 / Master (172.16.12.171).
Retrieve the application DB password:
cat /opt/flotomate/main-server/lib/boot-hosted-exec.confCopy
MotadataPatroniHADBConfigfrom/opt/HAto the home directory.Give it execute permissions and run it:
chmod 777 MotadataPatroniHADBConfig
./MotadataPatroniHADBConfigEnter the DB password when prompted.

Enter
ywhen asked to reload and restart Patroni members. Perform this twice and if the version is given then press enter.
Master DB configuration is complete.
Step 8: Run DB Configuration on the Slave
Run the following steps on APP + DB Node 2 / Slave (172.16.12.177).
Run
MotadataPatroniHADBConfig:chmod 777 MotadataPatroniHADBConfig
./MotadataPatroniHADBConfigEnter the same DB password you used in Step 7.

Slave DB configuration is complete.
Check the status of patroni service using the command:
systemctl status patroni
If an old HA configuration already exists, remove it after taking a backup:
rm -rf /opt/HA
Step 9: Configure the Application HA Observer
Run the following steps on the Observer machine (172.16.13.42).
Run this script as a normal user. Do not use root or sudo. The script will fail if run as root.
Give
MotadataAppHASetupexecute permissions and run it:chmod 777 MotadataAppHASetup
./MotadataAppHASetupPress Enter at every key-pair generation prompt until key generation completes.

Enter the following values when prompted:
Prompt Value Username for SSH Common SSH username for both nodes Port for SSH SSH port (default: 22)Master Server IP 172.16.12.171Master Server Password Enter twice when prompted Slave Server IP 172.16.12.177Slave Server Password Enter twice when prompted 

Press Enter twice at the second key-pair generation prompt.

Application HA Observer configuration is complete. Verify the setup by checking logs at /opt/HA/logs.
Troubleshooting
Use this section to diagnose common issues after completing the 3-machine standalone setup.
Nginx is active on the Slave after setup
Cause: Nginx started automatically during the Slave setup. An active Nginx service on the Slave causes routing conflicts with the Observer.
Fix: Stop Nginx on the Slave and verify all services are inactive before proceeding:
systemctl stop nginx
/opt/HA permission error during setup
Cause: The /opt/HA directory is owned by a different user than the one running the setup scripts.
Fix: Correct the ownership on the affected machine:
chown -R motadata:motadata /opt/HA
Machines cannot communicate with each other
Cause: One or more required firewall ports are blocked between machines.
Fix: Confirm the following ports are open between each machine pair:
| Source | Destination | Ports |
|---|---|---|
| Observer | APP + DB Node 1 and Node 2 | 80 (optional), 443 |
| Observer | APP + DB Node 1 and Node 2 | 5432, 8008 |
| APP + DB Node 1 (Master) | Observer | 2379, 2380, 5000 |
| APP + DB Node 2 (Slave) | Observer | 2379, 2380, 5000 |
| APP + DB Node 1 (Master) | APP + DB Node 2 (Slave) | 5432, 8008 |
Check both OS-level and network-level firewall rules on each machine.
Distributed HA Deployment (5 Machines)
In this layout, the application and database tiers run on separate dedicated machines. This model combines automatic failover with independent tier scaling. Use it for large enterprises where application and database workloads must be isolated.
Prerequisites
Before starting, confirm the following:
- Operating System: Ubuntu 22, Ubuntu 24, RHEL 9.4, or RHEL 9.6
- PostgreSQL Version: 16 or 17
- 5 machines provisioned and reachable over the network
- ServiceOps installed on both APP 1 and APP 2 (follow the Standalone Installation Guide)
- Root or sudo access on all 5 machines
- Setup scripts extracted on their respective machines:
MotadataETCDSetupU24on the Observer machineMotadataPatroniSetupU24on both DB machinesMotadataAppHASetupon the Observer machine
- Firewall ports open on each machine:
| Machine | Open Ports |
|---|---|
| Observer | 80 (Optional), 443, 2379, 2380, 5000, 7000 |
| APP 1 and APP 2 | 80 (Optional), 443 |
| DB 1 and DB 2 | 5432, 8008 |
Architecture Overview
The 5-machine distributed HA setup assigns a dedicated role to each machine:
| Role | Machine | Example IP | Ports |
|---|---|---|---|
| Observer / HAProxy / ETCD | 1 machine | 172.16.13.42 | 80, 443, 2379, 2380, 5000, 7000 |
| APP 1 (Master Application) | 1 machine | 172.16.12.171 | 80, 443 |
| APP 2 (Slave Application) | 1 machine | 172.16.12.177 | 80, 443 |
| DB 1 (Master Database) | 1 machine | 172.16.12.202 | 5432, 8008 |
| DB 2 (Slave Database) | 1 machine | 172.16.12.216 | 5432, 8008 |
HAProxy load-balances application traffic across APP 1 and APP 2 on ports 80 and 443, and routes database connections to the Patroni Leader on port 5000 and 7000. ETCD manages distributed consensus on ports 2379 and 2380. The Observer detects APP 1 failure and triggers master.sh and slave.sh failover scripts.
Procedure
Step 1: Download Setup Files
Download the zip file containing all setup files from the Download Links page and extract it on each machine before proceeding.
Step 2: Set Up the Observer (ETCD and HAProxy)
Run the following steps on the Observer machine (172.16.13.42).
Give
MotadataETCDSetupU24execute permissions and run it:chmod 777 MotadataETCDSetupU24
./MotadataETCDSetupU24
Type
yeswhen asked whether to install and configure ETCD.
Enter
1when asked for the ETCD node number. This setup uses a single ETCD node.
Maximum ETCD Cluster NodesThis setup supports a maximum of 7 ETCD cluster nodes. Leave all additional node prompts blank for a single-node setup.
Leave all additional ETCD node prompts blank and press Enter.

Type
yeswhen asked whether to install and configure HAProxy.
Enter the DB Node 1 (Master DB) IP address, for example
172.16.12.202. Then enter the DB Node 2 (Slave DB) IP address, for example172.16.12.216.
noteDB Node 1 = Master DB. DB Node 2 = Slave DB.
Enter the APP Node 1 (Master APP) IP address, for example
172.16.12.171. Then enter the APP Node 2 (Slave APP) IP address, for example172.16.12.177.
noteAPP Node 1 = Master APP. APP Node 2 = Slave APP.
ETCD and HAProxy setup is complete.
Verify the HAProxy Configuration
Open /etc/haproxy/haproxy.cfg and confirm it matches this structure:

global
maxconn 100
defaults
log global
mode tcp
retries 2
timeout client 30m
timeout connect 4s
timeout server 30m
timeout check 5s
listen stats
mode http
bind *:7000
stats enable
stats uri /
listen postgres
bind *:5000
option httpchk
http-check expect status 200
default-server inter 3s fall 3 rise 2 on-marked-down shutdown-sessions
server etcd1 172.16.12.202:5432 maxconn 100 check port 8008
server etcd2 172.16.12.216:5432 maxconn 100 check port 8008
listen backend
bind *:80
balance roundrobin
mode tcp
option tcp-check
server ubuntu1 172.16.12.171:80 check port 80
server ubuntu2 172.16.12.177:80 check port 80
Confirm the following ports are open before continuing: 80 and 443 on the Observer and both APP machines; 2379, 2380, and 5000 on the Observer; 5432, 7000, and 8008 on both DB machines.
Verify ETCD Service Status
Check that the ETCD service is running:
systemctl status motadata_etcd
If the service is inactive, start it:
systemctl start motadata_etcd
Step 3: Configure Master DB with Patroni
Run the following steps on DB 1 (Master DB) (172.16.12.202).
Give
MotadataPatroniSetupU24execute permissions and run it:chmod 777 MotadataPatroniSetupU24
./MotadataPatroniSetupU24Enter
1when asked whether this machine is Node 1 or Node 2. Then enter the Slave DB IP address:172.16.12.216.
Enter the ETCD IP address when prompted:
172.16.13.42.
Patroni setup on the Master DB is complete.
Step 4: Configure Slave DB with Patroni
Run the following steps on DB 2 (Slave DB) (172.16.12.216).
Give
MotadataPatroniSetupU24execute permissions and run it:chmod 777 MotadataPatroniSetupU24
./MotadataPatroniSetupU24Enter
2when asked whether this machine is Node 1 or Node 2. Enter the Master DB IP address and the ETCD IP address when prompted.
Verify that the Patroni service on the Slave DB is inactive after setup:
systemctl status patroni
If it shows
runningoractive, stop it:systemctl stop patroni
Patroni on the Slave DB starts automatically during Step 5 DB configuration. Starting it early causes split-brain issues.
Step 5: Run DB Configuration on the Master DB
Run the following steps on DB 1 (Master DB) (172.16.12.202).
Retrieve the application DB password from the Master APP machine:
cat /opt/flotomate/main-server/lib/boot-hosted-exec.conf
Copy
MotadataPatroniHADBConfigfrom/opt/HAto the home directory. Give it execute permissions and run it:chmod 777 MotadataPatroniHADBConfig
./MotadataPatroniHADBConfigEnter the DB password you retrieved in step 1.
Enter
ywhen asked to reload and restart Patroni members. Perform this twice and if the version is given then press enter.
Master DB configuration is complete.
Step 6: Run DB Configuration on the Slave DB
Run the following steps on DB 2 (Slave DB) (172.16.12.216).
Run
MotadataPatroniHADBConfig:./MotadataPatroniHADBConfigEnter the same DB password you used on the Master DB.

Slave DB configuration is complete.
If an old HA configuration already exists, remove it after taking a backup:
rm -rf /opt/HA
Step 7: Configure the Master Application
Run the following steps on APP 1 (Master APP) (172.16.12.171).
Copy MotadataPatroniHAMasterSlaveAppConfig from the Master DB /opt/HA folder to the Master APP machine. Give it execute permissions and run it:
chmod 777 MotadataPatroniHAMasterSlaveAppConfig
./MotadataPatroniHAMasterSlaveAppConfig
Enter the Observer IP address when prompted:
172.16.13.42.
Enter
masterwhen asked for the machine role.
Master application configuration completes.

Step 8: Configure the Slave Application
Run the following steps on APP 2 (Slave APP) (172.16.12.177).
Copy MotadataPatroniHAMasterSlaveAppConfig to the Slave APP machine. Give it execute permissions and run it:
chmod 777 MotadataPatroniHAMasterSlaveAppConfig
./MotadataPatroniHAMasterSlaveAppConfig
Enter the Observer IP address when prompted:
172.16.13.42.Enter
slavewhen asked for the machine role.
Enter the Master APP DB password when prompted.
Use the Master APP DB PasswordRetrieve the DB password from the Master APP configuration file. The password must be identical on all machines.

Slave application configuration is complete.
Step 9: Configure HA Observer for Application Failover
Run the following steps on the Observer machine (172.16.13.42).
Run this script as a normal user. Do not use root or sudo. The script will fail if run as root.
Give
service_desk_ha_CIexecute permissions and run it:chmod 777 service_desk_ha_CI
./service_desk_ha_CI
Press Enter repeatedly at each key-pair generation prompt until generation completes.
Enter the following values when prompted:
Prompt Value SSH username OS username on both APP machines SSH port Default is 22Master APP IP 172.16.12.171
Enter the Master APP password twice when prompted.

Enter the Slave APP IP address (
172.16.12.177). Enter the Slave APP password twice when prompted.Enter
testwhen asked for email configuration.
Press Enter at the second key-pair generation prompt.

Observer configuration for application HA is complete. Verify the setup by checking logs:
cat /opt/HA/logs
Troubleshooting
Use this section to diagnose common issues after completing the 5-machine distributed setup.
Nginx is running on the Slave APP after setup
Cause: Nginx started automatically on APP 2 during installation. An active Nginx service on the Slave APP causes routing conflicts with the Observer.
Fix: Stop and disable Nginx on APP 2:
systemctl stop nginx
systemctl disable nginx
/opt/HA has incorrect ownership
Cause: The /opt/HA directory is owned by a different user than the one used during configuration. Failover scripts fail when they cannot write to this directory.
Fix: Correct the ownership on both Master and Slave APP machines:
chown -R motadata:motadata /opt/HA
Machines cannot communicate with each other
Cause: One or more required firewall ports are blocked between machines.
Fix: Confirm the following ports are open between each machine pair:
| Source | Destination | Ports |
|---|---|---|
| Observer | Master APP and Slave APP | 80 (optional), 443 |
| Observer | Master DB and Slave DB | 5432, 8008 |
| Master DB | Observer | 2379, 2380, 5000 |
| Slave DB | Observer | 2379, 2380, 5000 |
| Master DB | Slave DB | 5432, 8008 |
Check both OS-level and network-level firewall rules on each machine.
Patroni on Slave DB is active before Step 5
Cause: Patroni started automatically during the Slave DB Patroni setup in Step 4. Starting it before DB configuration causes split-brain issues.
Fix: Stop Patroni on the Slave DB before running Step 6:
systemctl stop patroni
HTTPS port not listening after restart
Cause: The CertificateFilePath or KeyFilePath in appsettings.json still has a leading underscore, or the file path is incorrect for the OS.
Fix: Open appsettings.json and confirm the leading underscore is removed from both CertificateFilePath and KeyFilePath. Verify the file paths exist and use the correct path separator for the OS. Restart the poller service and re-run the verification commands.
Best Practices
Follow these recommendations to keep your Patroni-based HA environment stable and recoverable.
- Back up before every configuration change. Take a full database backup before running any HA setup script in a production environment. Restoring from backup is faster than debugging a failed configuration.
- Synchronize time across all nodes. ETCD relies on clock consistency for leader election. Run NTP on every machine and verify clocks are in sync before starting the setup.
- Use the same OS and PostgreSQL version on all nodes. Version drift between Master and Slave causes replication failures. Confirm all nodes run identical OS and PostgreSQL versions before proceeding.
- Verify firewall ports before running any installer. Blocked ports are the most common setup failure. Check all required ports are open at both the OS and network level before starting Step 1.
- Never start Patroni on the Slave manually before DB configuration runs. Patroni on the Slave must remain inactive until the DB configuration step activates it. Starting it early causes split-brain and data inconsistency.
- Run the Application HA Observer as a non-root user. The
MotadataAppHASetupandservice_desk_ha_CIscripts must run as a standard OS user. Root execution causes the scripts to fail silently. - Keep
/opt/HAowned by the same OS user on all nodes having sudo rights. Failover scripts write to this directory. Incorrect ownership prevents failover from executing. Use the user which is common in all machines and having sudo rights. You can change the ownership using the below command:- Syntax:
chown -R <username>:<username> /opt/HA - Example:
chown -R motadata:motadata /opt/HA
- Syntax:
- Monitor HAProxy stats after setup. The stats endpoint on port
7000shows which node is currently active. Check it after setup to confirm HAProxy is routing to the correct primary node. - Test failover after completing setup. Simulate a Master failure in a staging environment to confirm Patroni promotes the Slave and HAProxy reroutes traffic as expected. Do not assume failover works without testing it.
- Keep Nginx inactive on Slave application nodes. Nginx must not run on the Slave APP. An active Nginx service on the Slave causes routing conflicts with the Observer. Disable it after setup and verify it does not restart on reboot.