Docker (Mac or Linux)

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


The Docker image is intended for development/testing purposes only, and has not been prepared for production use. The images use default connection settings, which are very permissive, and not suitable for any kind of production setup. These should be updated before using the image for production use. The PostgreSQL manual explains how to make them more restrictive.

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 choose a different port for coordinator service with the MASTER_EXTERNAL_PORT environment variable. For example:

MASTER_EXTERNAL_PORT=5433 COMPOSE_PROJECT_NAME=citus docker-compose up -d

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