This runbook deploys a Citus Worker Node that will join the Citus cluster.
This procedure is identical for worker1 and worker2.
| Host | Role | WireGuard IP |
|---|---|---|
| coord1 | Primary Coordinator | 92.243.18.209 |
| coord2 | Coordinator Standby | 92.243.18.66 |
| worker1 | Citus Worker | 92.243.18.201 |
| worker2 | Citus Worker | 92.243.18.208 |
This guide assumes:
16/main)psql --version
sudo pg_lsclusters
Expected:
Ver Cluster Port Status
16 main 5432 online
sudo apt update
sudo apt install -y postgresql-16-citus-14.1
Verify:
dpkg -l | grep postgresql-16-citus
Check the current preload libraries.
sudo -u postgres psql -Atc \
"SHOW shared_preload_libraries;"
If empty:
sudo pg_conftool 16 main set shared_preload_libraries citus
If another extension is already configured:
sudo pg_conftool 16 main set \
shared_preload_libraries 'citus,pg_stat_statements'
Restart PostgreSQL.
sudo systemctl restart postgresql
Verify:
sudo -u postgres psql -Atc \
"SHOW shared_preload_libraries;"
Expected:
citus
sudo -u postgres createdb citus_cluster
Install the extension.
sudo -u postgres psql -d citus_cluster \
-c "CREATE EXTENSION citus;"
Verify:
sudo -u postgres psql -d citus_cluster \
-c "SELECT citus_version();"
Configure PostgreSQL to listen on localhost and the appropriate WireGuard address.
sudo pg_conftool 16 main set \
listen_addresses '127.0.0.1,92.243.18.201'
sudo pg_conftool 16 main set \
listen_addresses '127.0.0.1,92.243.18.208'
Restart PostgreSQL.
sudo systemctl restart postgresql
Verify.
sudo ss -lntp | grep 5432
Expected on worker1:
127.0.0.1:5432
92.243.18.201:5432
Expected on worker2:
127.0.0.1:5432
92.243.18.208:5432
Append the following to /etc/hosts.
92.243.18.209 coord1
92.243.18.66 coord2
92.243.18.201 worker1
92.243.18.208 worker2
Verify.
getent hosts coord1
getent hosts coord2
Locate the active file.
sudo -u postgres psql -Atc \
"SHOW hba_file;"
Create a backup.
HBA=$(sudo -u postgres psql -Atc "SHOW hba_file")
sudo cp "$HBA" "$HBA.bak"
Append the following rule.
# ==================================================
# Citus Coordinator
# ==================================================
host all all 92.243.18.209 /32 trust
Reload PostgreSQL.
sudo systemctl reload postgresql
Validate.
sudo -u postgres psql -P pager=off -c "
SELECT
line_number,
address,
auth_method,
error
FROM pg_hba_file_rules
WHERE address::text LIKE '92.243.%'
OR error IS NOT NULL;"
The error column should be empty.
If UFW is enabled, allow the coordinator to connect.
sudo ufw allow in on wg0 \
from 92.243.18.209 \
to 92.243.18.201 \
port 5432 proto tcp
sudo ufw allow in on wg0 \
from 92.243.18.209 \
to 92.243.18.208\
port 5432 proto tcp
Verify.
sudo ufw status numbered
Verify WireGuard communication.
ping -c3 coord1
Verify PostgreSQL connectivity.
nc -zv coord1 5432
Run the following validation script.
echo "=== PostgreSQL ==="
sudo pg_lsclusters
echo
echo "=== Citus Package ==="
dpkg -l | grep postgresql-16-citus
echo
echo "=== Preload ==="
sudo -u postgres psql -Atc \
"SHOW shared_preload_libraries;"
echo
echo "=== Citus Version ==="
sudo -u postgres psql -d citus_cluster \
-c "SELECT citus_version();"
echo
echo "=== PostgreSQL Listener ==="
sudo ss -lntp | grep 5432
echo
echo "=== HBA Validation ==="
sudo -u postgres psql -Atc "
SELECT count(*)
FROM pg_hba_file_rules
WHERE error IS NOT NULL;"
Expected results:
PostgreSQL 16.14 running
Citus 14.1 installed
shared_preload_libraries = citus
citus_cluster database exists
citus extension installed
PostgreSQL listening on:
127.0.0.1:543292.243.18.201:5432127.0.0.1:543292.243.18.209:5432pg_hba.conf validation returns 0 errors
Coordinator reachable over the WireGuard network
Once both workers have successfully completed this runbook, connect to coord1 and register them with Citus.
SELECT * FROM citus_add_node('worker1', 5432);
SELECT * FROM citus_add_node('worker2', 5432);
Verify.
SELECT
nodeid,
nodename,
nodeport,
noderole,
isactive
FROM pg_dist_node
ORDER BY nodeid;
Expected:
coord1 primary
worker1 primary
worker2 primary
After both workers have been successfully registered: