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 https://get.docker.com/ | sh
sudo usermod -aG docker $USER && exec sg docker newgrp `id -gn`
sudo systemctl start docker
sudo curl -sSL https://github.com/docker/compose/releases/download/1.16.1/docker-compose-`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 https://raw.githubusercontent.com/citusdata/docker/master/docker-compose.yml > 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.
Note
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 0.0.0.0:5432: 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
Note
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.