Ubuntu or Debian

This section describes the steps needed to set up a single-node Citus cluster on your own Linux machine from deb packages.

1. Install PostgreSQL 16 and the Citus extension

# Add Citus repository for package manager
curl https://install.citusdata.com/community/deb.sh | sudo bash

# install the server and initialize db
sudo apt-get -y install postgresql-16-citus-12.1

2. Initialize the Cluster

Let’s create a new database on disk. For convenience in using PostgreSQL Unix domain socket connections, we’ll use the postgres user.

# this user has access to sockets in /var/run/postgresql
sudo su - postgres

# include path to postgres binaries
export PATH=$PATH:/usr/lib/postgresql/16/bin

cd ~
mkdir citus
initdb -D citus

Citus is a Postgres extension. To tell Postgres to use this extension you’ll need to add it to a configuration variable called shared_preload_libraries:

echo "shared_preload_libraries = 'citus'" >> citus/postgresql.conf

3. Start the database server

Finally, we’ll start an instance of PostgreSQL for the new directory:

pg_ctl -D citus -o "-p 9700" -l citus_logfile start

Above you added Citus to shared_preload_libraries. That lets it hook into some deep parts of Postgres, swapping out the query planner and executor. Here, we load the user-facing side of Citus (such as the functions you’ll soon call):

psql -p 9700 -c "CREATE EXTENSION citus;"

4. Verify that installation has succeeded

To verify that the installation has succeeded, and Citus is installed:

psql -p 9700 -c "select citus_version();"

You should see details of the Citus extension.

At this step, you have completed the installation process and are ready to use your Citus cluster. To help you get started, we have a tutorial which has instructions on setting up a Citus cluster with sample data in minutes.