Docker (Mac or Linux)ΒΆ

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

1. Install Docker Community Edition and Docker Compose

On Mac:

  • Install Docker.
  • Start Docker by clicking on the application’s icon.

On Linux:

curl -sSL | sh
sudo usermod -aG docker $USER && exec sg docker newgrp `id -gn`
sudo systemctl start docker

sudo curl -sSL`uname -s`-`uname -m` -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

The above version of Docker Compose is sufficient for running Citus, or you can install the latest version.

2. Start the Citus Cluster

Citus uses Docker Compose to run and connect containers holding the database coordinator node, workers, and a persistent data volume. To create a local cluster download our Docker Compose configuration file and run it

curl -L > docker-compose.yml
COMPOSE_PROJECT_NAME=citus docker-compose up -d

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


If you already 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” (coordinator) 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 coordinator node has picked up the desired worker configuration. First start the psql shell on the coordinator (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.

Once you have the cluster up and running, you can visit our tutorials on multi-tenant applications or real-time analytics to get started with Citus in minutes.

4. Shut down the cluster when ready

When you wish to stop the docker containers, use Docker Compose:

COMPOSE_PROJECT_NAME=citus docker-compose down -v


Please note that Citus reports anonymous information about your cluster to the Citus Data company servers. To learn more about what information is collected and how to opt out of it, see Checks For Updates and Cluster Statistics.