CockroachDB is a highly resilient and scalable distributed SQL database designed to easily handle large-scale data workloads. When installed on Ubuntu, it provides an open-source, cloud-native database solution that delivers strong consistency, high availability, and horizontal scalability. CockroachDB’s architecture allows it to automatically replicate and distribute data across multiple nodes, ensuring data integrity and minimizing downtime despite hardware failures. Its compatibility with PostgreSQL makes it a versatile choice for developers seeking a robust database system capable of handling demanding applications. Installing CockroachDB on Ubuntu allows users to leverage these advanced features while benefiting from the security and stability of the Ubuntu operating system.
CockroachDB stores your data in multiple locations, making data delivery faster. Also, it’s easy to scale and provides high availability and fault tolerance for your applications.
In this guide, we’ll show you how to install the CockroachDB cluster on Ubuntu 24.04 servers.
Prerequisites
Before going further, make sure you have the following:
- Two or three Ubuntu 24.04 servers.
- A non-root user with administrator privileges.
Setting up user
Before installing CockroachDB, you’ll create a new system user and group cockroach. This will be used for running the CockroachDB service.
First, run the command below to add a new system user cockroach with the home directory /opt/cockroachdb.
sudo adduser –home /opt/cockroachdb –system –group cockroach
Now change the ownership of the /opt/cockroachdb directory to the user and group cockroach with the following:
sudo chown -R cockroach:cockroach /opt/cockroachdb
Downloading CockroachDB binary
To install CockroachDB, you can easily download it from the GitHub page and move the CockroachDB binary file to the bin directory on your Ubuntu system.
Visit the CockroachDB GitHub page and grab the link for the latest version. Download it with the wget command like this:
wget https://binaries.cockroachdb.com/cockroach-v24.1.1.linux-amd64.tgz
Once the download is complete, extract the CockroachDB and move the cockroach binary file to the /usr/bin directory.
tar -xf cockroach-v24.1.1.linux-amd64.tgz
cp -i cockroach-*/cockroach /usr/bin/
Now check the CockroachDB version with the following:
cockroach –version
In the output below, you can see that CockroachDB v24 is installed.
Generating TLS certificates
To create a CockroachDB cluster, you must generate an SSL/TLS certificate to secure the cluster. You need to generate and distribute CA certificates across servers, and then generate certificates for users and servers.
Before going further, run the command below on both server1 and server2. With this, you’ll create directories certs and private for string TLS certificates.
mkdir -p /opt/cockroachdb/{certs,private}
Generating CA certificate
In this section, you’ll generate a CA certificate from the server1 and upload it to the server2 through scp or secure copy.
On the server1, run the command below to generate CA (Certificate Authority) certificates. The CA certificate ca.crt and ca.key will be generated.
cockroach cert create-ca
–certs-dir=/opt/cockroachdb/certs
–ca-key=/opt/cockroachdb/private/ca.key
Now upload the ca.crt and ca.key to the server2 with the scp or secure copy. Make sure you can log in to the server2 without a problem.
scp /opt/cockroachdb/private/ca.key [email protected]:/opt/cockroachdb/private/
scp /opt/cockroachdb/certs/ca.crt [email protected]:/opt/cockroachdb/certs/
Generating client certificate
After generating the CA certificate, you’ll generate a client certificate for managing the CockroachDB cluster. Only users with this certificate can connect and manage the CockroachDB cluster.
To generate and sign the client certificate for the user rootRun the following cockroach command.
cockroach cert create-client \
root \
–certs-dir=/opt/cockroachdb/certs \
–ca-key=/opt/cockroachdb/private/ca.key
Generating server certificates
In this section, you’ll generate server certificates on both server1 and server2.
On the server1, run the command below to generate the server certificate. Make sure to change the IP address and hostname with your information.
cockroach cert create-node \
server1 \
192.168.5.15 \
localhost \
–certs-dir=/opt/cockroachdb/certs \
–ca-key=/opt/cockroachdb/private/ca.key
Now, move to the server2 and generate a node certificate with the following. Change the IP address and hostname with server2 information.
cockroach cert create-node \
server2 \
192.168.5.16 \
localhost \
–certs-dir=/opt/cockroachdb/certs \
–ca-key=/opt/cockroachdb/private/ca.key
Lastly, run the command below on both server1 and server2 to change the ownership of certs and private directories to the user cockroach.
sudo chown -R cockroach:cockroach /opt/cockroachdb/{certs,private}
Running CockroachDB as a service
After you’ve generated SSL/TLS certificates, you’ll create a systemd service file for each CockroachDB server. This allows you to run CockroachDB in the background and you can easily manage it with the systemctl.
Create a new systemd service file /etc/systemd/system/cockroachdb.service with the nano editor.
sudo nano /etc/systemd/system/cockroachdb.service
For the server1, insert the configuration below. On the --advertise-addr option, input the server1 IP address. In the --join option, input both the server1 and server2 IP addresses.
[Unit]
Description=Cockroach Database cluster node
Requires=network.target
[Service]
Type=notify
WorkingDirectory=/opt/cockroachdb
ExecStart=/usr/bin/cockroach start --certs-dir=/opt/cockroachdb/certs --advertise-addr=192.168.5.15 --join=192.168.5.15,192.168.5.16
TimeoutStopSec=60
Restart=always
RestartSec=10
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=cockroach
User=cockroach
[Install]
WantedBy=default.target
For the server2, insert the configuration below. On the --advertise-addr option, input the server2 IP address. In the --join option, input both the server1 and server2 IP addresses.
[Unit]
Description=Cockroach Database cluster node
Requires=network.target
[Service]
Type=notify
WorkingDirectory=/opt/cockroachdb
ExecStart=/usr/bin/cockroach start --certs-dir=/opt/cockroachdb/certs --advertise-addr=192.168.5.16 --join=192.168.5.15,192.168.5.16
TimeoutStopSec=60
Restart=always
RestartSec=10
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=cockroach
User=cockroach
[Install]
WantedBy=default.target
Save and exit the file when you’re done.
Now run the systemctl command below to reload the systemd manager and apply your changes.
sudo systemctl daemon-reload
And then start and enable the cockroachdb service on the server1 and server2.
sudo systemctl enable –now cockroachdb
Lastly, check the cockroachdb service status with the following:
sudo systemctl status cockroachdb
You’ll see the cockroachdb service is running on the server1 and server2.
Creating CockroachDB cluster
So the CockroachDB is running on both server1 and server2. You can now initialize the CockroachDB cluster from one of these servers.
On the server1, run the cockroach init command below to initialize the CockroachDB cluster. If successful, you’ll see an output Cluster successfully initialized.
cockroach init –certs-dir=/opt/cockroachdb/certs –host=192.168.5.15:26257
Now run the command below to check the cluster initialization log. If the CockroachDB cluster is running, you’ll get the output CockroachDB node starting.
grep ‘node starting’ /opt/cockroachdb/cockroach-data/logs/cockroach.log -A 11
Next, run the cockroach command below to verify the list servers and CockroachDB cluster status.
sudo cockroach node –certs-dir=/opt/cockroachdb/certs –host=server1 ls
sudo cockroach node –certs-dir=/opt/cockroachdb/certs –host=server1 status
You can see below that server1 and server2 are available on the CockroachDB cluster with the status active.
Now run the cockroach sql command below to access the CockroachDB shell. You can manage the database and user in the CockroachDB cluster from here.
sudo cockroach sql –certs-dir=/opt/cockroachdb/certs –host=server1:26257
Run the following queries to create a new admin user alice with password p4ssw0rd.
CREATE USER alice WITH PASSWORD ‘p4ssw0rd’;
GRANT admin TO alice;
Type quit to exit from the CockroachDB server.
Access CockroachDB web administration
By default, the CockroachDB web administration is running on port 8080. This allows you to manage CockroachDB through a web browser.
To access the CockroachDB web administration dashboard, visit http://server1:8080 using your web browser. Enter your username and password, then click Log in.
If you have the correct username and password, you’ll see the CockroachDB administration dashboard like the following:
Conclusion
Congratulations! You’ve completed the installation of the CockroachDB cluster on the Ubuntu 24.04 server. You’ve also learned how to check the status of the CockroachDB cluster through the command line and web administration dashboard. Lastly, you’ve created an admin user through the CockroachDB SQL shell.
