How to Setup CockroachDB Cluster on Ubuntu 24.04

CockroachDB is a highly distributed SQL database platform that designed to handle large-scale data workloads across multiple nodes. It is an open-source, cloud-native database that provides strong consistency, high availability, and automatic scaling.

In this article, we will guide you through the process of installing a CockroachDB cluster on Ubuntu 24.04.

Prerequisites

Before we begin, ensure that you have the following:

Step 1: Installing CockroachDB on Ubuntu

First, update your system software packages to the most recent version and then install the required dependencies as shown.

sudo apt update -y
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

Next, visit the official CockroachDB download page to get the latest version or use the following wget command to download it directly.

wget -qO- https://binaries.cockroachdb.com/cockroach-v24.1.1.linux-amd64.tgz | tar xvz

Once downloaded, move the binary to a directory in your PATH and verify the installation.

sudo cp -i cockroach-v24.1.1.linux-amd64/cockroach /usr/local/bin/
cockroach version

Step 2: Initializing the CockroachDB Cluster

To initialize the CockroachDB cluster, create a directory for cockroachdb data and start the CockroachDB node, which sets up the initial cluster configuration.

sudo mkdir -p /var/lib/cockroach
sudo chown $(whoami) /var/lib/cockroach
cockroach start-single-node --insecure --store=/var/lib/cockroach --listen-addr=localhost:26257 --http-addr=localhost:8080

Next, open another terminal and run the following command to verify the cluster initialization by connecting to the CockroachDB SQL shell.

cockroach sql --insecure --host=localhost:26257

To exit the SQL shell, type q and press Enter.

Step 3: Starting CockroachDB as a Background Service

To run CockroachDB as a background service, we will create a systemd service file.

sudo nano /etc/systemd/system/cockroach.service

Add the following configuration.

[Unit]
Description=CockroachDB
Documentation=https://www.cockroachlabs.com/docs/
After=network.target

[Service]
Type=notify
ExecStart=/usr/local/bin/cockroach start-single-node --insecure --store=/var/lib/cockroach --listen-addr=localhost:26257 --http-addr=localhost:8080
TimeoutStartSec=0
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Next, reload the systemd manager configuration, start the CockroachDB service, enable it to run on system startup, and check its current status.

sudo systemctl daemon-reload
sudo systemctl start cockroach
sudo systemctl enable cockroach
sudo systemctl status cockroach

The output should indicate that the CockroachDB service is active and running.

Step 4: Accessing the CockroachDB Admin UI

CockroachDB includes a web-based Admin UI for managing and monitoring your cluster at the following URL.

http://localhost:8080

The Admin UI provides various tabs to monitor the cluster, databases, and nodes. You can view metrics, performance details, and more.

Step 5: Creating and Managing CockroachDB Databases

To interact with CockroachDB, you can use the SQL shell.

cockroach sql --insecure --host=localhost:26257

To create and verify a database in CockroachDB.

CREATE DATABASE mydb;
SHOW DATABASES;

You should see the list of available databases, including mydb.

To create a table in the database.

USE mydb;
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name STRING,
    email STRING UNIQUE
);

Next, insert data into it and query it.

INSERT INTO users (name, email) VALUES ('Alice', '[email protected]'), ('Bob', '[email protected]');
SELECT * FROM users;

To exit the SQL shell, type q and press Enter.

Step 6: Secure the CockroachDB Cluster (Optional)

By default, the CockroachDB cluster is running in insecure mode, which is not recommended for production environments.

To secure the cluster, generate the necessary SSL certificate for the CockroachDB cluster using the following commands, which will generate ca.crt and ca.key in the /home/ravi/cert directory.

mkdir /home/ravi/cert
cockroach cert create-ca --certs-dir=/home/ravi/cert --ca-key=/home/ravi/cert/ca.key

Next, generate node certificates signed by the CA, which will generate node.crt and node.key in the /home/ravi/cert directory. Make sure to replace localhost with the hostname or IP address of your CockroachDB node.

cockroach cert create-node localhost --certs-dir=/home/ravi/cert --ca-key=/home/ravi/cert/ca.key

Now set the correct permissions on the certificate.

sudo chmod 600 /home/ravi/cert/*.crt /home/ravi/cert/*.key

Finally, modify your systemd service file ‘cockroach.service‘.

sudo nano /etc/systemd/system/cockroach.service

update the ExecStart line to include SSL/TLS and authentication flags.

cockroach start --certs-dir=/home/ravi/cert --listen-addr=localhost:26257 --http-addr=localhost:8080 --join=localhost:26257,localhost:26258,localhost:26259

After making these changes, reload the systemd manager configuration and restart CockroachDB to apply the new certificates.

sudo systemctl daemon-reload
sudo systemctl restart cockroach

Verify that CockroachDB is accessible using the new SSL/TLS certificates:

cockroach sql --certs-dir=/home/ravi/cert --host=localhost:26257

Conclusion

In this guide, we covered the steps to install and configure CockroachDB on Ubuntu 24.04. We walked through downloading and installing CockroachDB, initializing the cluster, running it as a background service, and accessing the Admin UI.

Additionally, we explored basic database operations using the SQL shell.