This section describes setting up a Citus cluster on a single machine using docker-compose.

1. Install docker and docker-compose

Follow the installation instructions for Docker Engine and Docker Compose on your platform.

2. Start the Citus Cluster

Citus uses docker-compose to run and connect containers holding the database master node, workers, and a persistent data volume. To create a local cluster download our docker-compose configuration file and run it

docker-compose -p citus up -d

The first time you start the cluster it builds its containers. Subsequent startups take a matter of seconds.


If you have PostgreSQL running on your machine you may encounter this error when starting the Docker containers:

Error starting userland proxy:
Bind for unexpected error address already in use

This is because the “master” service attempts to bind to the standard PostgreSQL port 5432. Simply adjust docker-compose.yml. Under the master section change the host port from 5432 to 5433 or another non-conflicting number.

- ports: ['5432:5432']
+ ports: ['5433:5432']

3. Verify that installation has succeeded

To verify that the installation has succeeded we check that the master node has picked up the desired worker configuration. First start the psql shell on the master node:

docker exec -it citus_master psql -U postgres

Then run this query:

select * from master_get_active_worker_nodes();

You should see a row for each worker node including the node name and port.

4. Shut down the cluster when ready

When you wish to stop the docker containers, use docker-compose:

docker-compose -p citus down