Quickly Build a Multi‑Node Citus 12.1 Cluster on Alibaba Cloud ECS with Containers

Alibaba Cloud ECS

Machine nodes

Two ECS instances in the same region.

Each instance has 2 CPU cores and 2 GB RAM.

One instance runs the coordinator (internal IP 172.18.60.11).

The other runs the worker (internal IP 172.18.60.12).

Operating system

Both nodes run Alibaba Cloud Linux 3.

lsb_release -a
LSB Version:    :core-4.1-amd64:core-4.1-noarch
Distributor ID: AlibabaCloud
Description:    Alibaba Cloud Linux release 3 (Soaring Falcon)
Release:        3
Codename:       SoaringFalcon

Docker installation

Execute the following steps on each node:

Add the Docker‑CE repository.

sudo dnf config-manager --add-repo=https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo

Install the Alibaba Cloud Linux 3 compatible DNF plugin.

sudo dnf -y install dnf-plugin-releasever-adapter --repo alinux3-plus

Install Docker. sudo dnf -y install docker-ce --nobest Start Docker and enable it at boot.

sudo systemctl start docker
sudo systemctl enable docker

Verify Docker status.

sudo systemctl status docker

Security group

Port 5432 (PostgreSQL) must be allowed; intra‑region internal traffic is permitted by default.

Citus 12.1 cluster setup

Use the official image citusdata/citus:12.1.

Start coordinator node

mkdir -p citus-coordinator/data
docker run -d --name citus-coordinator \
  -v $(pwd)/citus-coordinator/data:/var/lib/postgresql/data \
  -p 5432:5432 \
  -e POSTGRES_USER=citus \
  -e POSTGRES_PASSWORD=citus \
  -e PGUSER=citus \
  -e PGPASSWORD=citus \
  -e POSTGRES_HOST_AUTH_METHOD=trust \
  citusdata/citus:12.1

Start worker node

mkdir -p citus-worker00/data
docker run -d --name citus-worker00 \
  -v $(pwd)/citus-worker00/data:/var/lib/postgresql/data \
  -p 5432:5432 \
  -e POSTGRES_USER=citus \
  -e POSTGRES_PASSWORD=citus \
  -e PGUSER=citus \
  -e PGPASSWORD=citus \
  -e POSTGRES_HOST_AUTH_METHOD=trust \
  citusdata/citus:12.1

Cluster configuration

docker exec -it citus-coordinator psql -U citus
SELECT citus_set_coordinator_host('172.18.60.11', 5432);
SELECT * FROM citus_add_node('172.18.60.12', 5432);
SELECT * FROM citus_get_active_worker_nodes();

Verification with official example

Create user service schema

docker exec -it citus-coordinator psql -U citus
CREATE USER user_service;
SET citus.enable_schema_based_sharding TO ON;
CREATE SCHEMA AUTHORIZATION user_service;
\c citus user_service
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) NOT NULL
);

Run user service container

docker run -d --name usersvc \
  -p 6000:5000 \
  -e DB_HOST='172.18.60.11' \
  -e DB_NAME=citus \
  registry.cn-heyuan.aliyuncs.com/hacker-linner/citus-microsvc-user:1.0.1

Create sample users

curl -X POST -H "Content-Type: application/json" -d '[
  {"name": "John Doe", "email": "[email protected]"},
  {"name": "Jane Smith", "email": "[email protected]"},
  {"name": "Mike Johnson", "email": "[email protected]"},
  {"name": "Emily Davis", "email": "[email protected]"},
  {"name": "David Wilson", "email": "[email protected]"},
  {"name": "Sarah Thompson", "email": "[email protected]"},
  {"name": "Alex Miller", "email": "[email protected]"},
  {"name": "Olivia Anderson", "email": "[email protected]"},
  {"name": "Daniel Martin", "email": "[email protected]"},
  {"name": "Sophia White", "email": "[email protected]"}
]' http://localhost:6000/users

Response: {"message":"Users created successfully","user_ids":[1,2,3,4,5,6,7,8,9,10]}

List created users

curl http://localhost:6000/users

Verify shard placement on worker node

docker exec -it citus-coordinator psql -U citus
SELECT nodename, nodeport, table_name, pg_size_pretty(sum(shard_size))
FROM citus_shards
GROUP BY nodename, nodeport, table_name;

Result shows user_service.users stored on worker node 172.18.60.12 with size 32 kB.

References

https://www.citusdata.com/

https://docs.citusdata.com/

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

https://hacker-linner.com/