Official Guide to Installing a Distributed PostgreSQL (Citus) Cluster

Single‑node Citus

Docker (Mac & Linux)

Docker images are for development/testing only.

Start a Citus container:

# start the image
docker run -d --name citus -p 5432:5432 -e POSTGRES_PASSWORD=mypass \
           citusdata/citus:10.2

# verify it is running and Citus is installed
psql -U postgres -h localhost -d postgres -c "SELECT * FROM citus_version();"

If the host already runs PostgreSQL on port 5432, bind the container to a different host port with -p and use that port in subsequent psql commands.

Official tutorials:

https://docs.citusdata.com/en/v10.2/get_started/tutorial_multi_tenant.html#multi-tenant-tutorial

https://docs.citusdata.com/en/v10.2/get_started/tutorial_realtime_analytics.html#real-time-analytics-tutorial

Ubuntu or Debian

Install PostgreSQL 14 and Citus 10.2 from the Citus repository:

# Add Citus repository
curl https://install.citusdata.com/community/deb.sh | sudo bash

# Install server and extension
sudo apt-get -y install postgresql-14-citus-10.2

Initialize a new data directory and preload the extension:

sudo su - postgres
export PATH=$PATH:/usr/lib/postgresql/14/bin
mkdir citus
initdb -D citus
echo "shared_preload_libraries = 'citus'" >> citus/postgresql.conf
pg_ctl -D citus -o "-p 9700" -l citus_logfile start
psql -p 9700 -c "CREATE EXTENSION citus;"
psql -p 9700 -c "SELECT citus_version();"

Fedora, CentOS, or Red Hat

Install via the RPM repository:

# Add Citus repository
curl https://install.citusdata.com/community/rpm.sh | sudo bash

# Install Citus extension for PostgreSQL 14
sudo yum install -y citus102_14

# Preload the extension
echo "shared_preload_libraries = 'citus'" | sudo tee -a /var/lib/pgsql/14/data/postgresql.conf

# Allow remote connections (example, adjust for security)
sudo vi /var/lib/pgsql/14/data/postgresql.conf   # set listen_addresses = '*'
sudo vi /var/lib/pgsql/14/data/pg_hba.conf
# add lines:
# host    all   all   10.0.0.0/8   trust
# host    all   all   127.0.0.1/32 trust
# host    all   all   ::1/128      trust

sudo service postgresql-14 restart
sudo chkconfig postgresql-14 on
sudo -i -u postgres psql -c "CREATE EXTENSION citus;"

Multi‑node Citus

Ubuntu or Debian (all nodes)

Add the Citus repository:

curl https://install.citusdata.com/community/deb.sh | sudo bash

Install PostgreSQL 14 + Citus 10.2 and preload the extension:

sudo apt-get -y install postgresql-14-citus-10.2
sudo pg_conftool 14 main set shared_preload_libraries citus

Configure listening on all addresses and adjust pg_hba.conf for network access:

sudo pg_conftool 14 main set listen_addresses '*'
sudo vi /etc/postgresql/14/main/pg_hba.conf   # add appropriate host lines

Start PostgreSQL and create the Citus extension:

sudo service postgresql restart
sudo -i -u postgres psql -c "CREATE EXTENSION citus;"

Coordinator node (Ubuntu/Debian)

Add worker nodes (example worker-101 and worker-102 on port 5432):

sudo -i -u postgres psql -c "SELECT * FROM citus_add_node('worker-101', 5432);"
sudo -i -u postgres psql -c "SELECT * FROM citus_add_node('worker-102', 5432);"

Verify registration:

sudo -i -u postgres psql -c "SELECT * FROM citus_get_active_worker_nodes();"

Connect to the cluster:

sudo -i -u postgres psql

Fedora, CentOS, or Red Hat (all nodes)

Add the Citus repository:

curl https://install.citusdata.com/community/rpm.sh | sudo bash

Install PostgreSQL 14 + Citus and preload the extension:

sudo yum install -y citus102_14
echo "shared_preload_libraries = 'citus'" | sudo tee -a /var/lib/pgsql/14/data/postgresql.conf

Configure listening on all IPs and permissive authentication (adjust for security):

sudo vi /var/lib/pgsql/14/data/postgresql.conf   # set listen_addresses = '*'
sudo vi /var/lib/pgsql/14/data/pg_hba.conf
# add host lines for 10.0.0.0/8, 127.0.0.1/32, ::1/128 with trust

Start PostgreSQL and create the extension:

sudo service postgresql-14 restart
sudo chkconfig postgresql-14 on
sudo -i -u postgres psql -c "CREATE EXTENSION citus;"

Coordinator node (Fedora/CentOS/Red Hat)

Add worker nodes (same example):

sudo -i -u postgres psql -c "SELECT * FROM citus_add_node('worker-101', 5432);"
sudo -i -u postgres psql -c "SELECT * FROM citus_add_node('worker-102', 5432);"

Verify registration:

sudo -i -u postgres psql -c "SELECT * FROM citus_get_active_worker_nodes();"

Connect to the cluster:

sudo -i -u postgres psql

Additional resources

https://mp.weixin.qq.com/s?__biz=MzA4Mzc4NTE5MQ==∣=2692295935&idx=1&sn=e3a05af79961eb80f4f4e128c18b9f96&scene=21#wechat_redirect

https://mp.weixin.qq.com/s?__biz=MzA4Mzc4NTE5MQ==∣=2692295926&idx=1&sn=86c602e563adbae2aa1d854c3ccd1795&scene=21#wechat_redirect