How to install a CockroachDB cluster on Ubuntu 18.04

Looking for a scalable, cloud-friendly database? Look no further than CockroachDB.


Jack Wallen

CockroachDB is a scalable, distributed SQL database that can be deployed on-premises, in the cloud, or even across clouds. It's an always-on database cluster that can have an attached location to ensure low-latency to users, regardless of where they are. CockroachDB is also capable of surviving disk, machine, rack, and even datacenter failures with near-zero latency disruption and no manual intervention.

I want to walk you through the process of installing a CockroachDB cluster on Ubuntu Server 18.04.

SEE: Hiring kit: Database administrator (Tech Pro Research)

What you need

In order to make this process work, you need:

  • Three instances of Ubuntu Server 18.04.
  • Account with sudo privileges.

For our Ubuntu Servers, we'll use the following hostnames/IP addresses:

  • cockroachdbcontrol at
  • cockroachnode2 at
  • cockroachnode3 at

You can, of course, use whatever hostnames and IP addresses you need. If you do change those, make sure to do so throughout this tutorial.

Syncing time

First, make sure your servers' clocks are all in sync with one another. To do this, install chrony. 

Open a terminal window on each server and issue the command:

sudo apt-get install chrony -y

Once installed, you need to configure chrony with your country's NTP pool. On each server, issue the command:

sudo nano /etc/chrony/chrony.conf

You need to edit the default NTP pool lines and replace them with those of your country. For example, in the US those lines would be:

pool iburst maxsources 1
pool iburst maxsources 1
pool iburst maxsources 2
pool iburst maxsources 2

Save and close those files. Restart and enable chrony with the commands:

sudo systemctl restart chrony
sudo systemctl enable chrony

Install CockroachDB

CockroachDB isn't installed via the standard means. Instead, you need to download the binary file, extract it, and move it into the proper directory. This is done with the following commands:

tar -xvzf cockroach-latest.linux-amd64.tgz
sudo cp cockroach-*/cockroach /usr/local/bin/

Create the necessary certificates

Next, in order to communicate to one another, each CockroachDB server requires certificates. This can be done with OpenSSL, which is included with Ubuntu Server. The first thing to do is to create the necessary directory to house the certificates and then set the environment variable for the directory. This is done on all three servers.

First, create the necessary directory with the command:

mkdir -p ${HOME}/.cockroach-certs/

Next, set the environment variable with the command:

export COCKROACH_CERTS_DIR='${HOME}/.cockroach-cert

Go to cockroachdbcontrol and generate the certificate authority with the command:

cockroach cert create-ca --certs-dir=$COCKROACH_CERTS_DIR --ca-key=$COCKROACH_CERTS_DIR/ca.key

Now we can copy that key to the other servers using the scp command with the following commands (run on cockroachdbcontrol):

scp ~/.cockroach-certs/ca.crt ~/.cockroach-certs/ca.key USER@
scp ~/.cockroach-certs/ca.crt ~/.cockroach-certs/ca.key USER@

Where USER is the user account used to create the certificate directories on the two nodes.

Next, we need to create the client certificates that will be used to secure communications between the SQL shell and the cluster. The following command must be run on all three servers:

cockroach cert create-client root --certs-dir=$COCKROACH_CERTS_DIR --ca-key=$COCKROACH_CERTS_DIR/ca.key

Finally, we have to create the server certificates. Issue the following command on cockroachdbcontrol:

cockroach cert create-node localhost $(hostname) --certs-dir=$COCKROACH_CERTS_DIR --ca-key=$COCKROACH_CERTS_DIR/ca.key

Issue the following command on cockroachnode2:

cockroach cert create-node localhost $(hostname) --certs-dir=$COCKROACH_CERTS_DIR --ca-key=$COCKROACH_CERTS_DIR/ca.key

Issue the following command on cockroachnode3:

cockroach cert create-node localhost $(hostname) --certs-dir=$COCKROACH_CERTS_DIR --ca-key=$COCKROACH_CERTS_DIR/ca.key

Initialize the cluster

It's time to initialize our cluster. On cockroachdbcontrol, issue the command:

cockroach start --background --certs-dir=$COCKROACH_CERTS_DIR --advertise-host= --listen-addr=

You can check the cluster node status with the command:

cockroach node status --host=

The cockroachdbcontrol machine should be listed (Figure A).


Figure A: cockroachdbcontrol to Major Tom!

Joining the nodes

With the controller accepting connections, we can now join the nodes. Go to cockroachnode2 and issue the command:

cockroach start --background --certs-dir=$COCKROACH_CERTS_DIR --advertise-host= --listen-addr= --join=

Next, go to cockroachnode3 and issue the command:

cockroach start --background --certs-dir=$COCKROACH_CERTS_DIR --advertise-host= --listen-addr= --join=

Head back over to cockroachdbcontrol and issue the command:

cockroach node status --host=

You should now see that all nodes have been joined to the cluster (Figure B).


Figure B: All nodes have reported in.

Create a database user

Go back to cockroachdbcontrol and create a database by first logging into the shell with the command:

cockroach sql --certs-dir=$COCKROACH_CERTS_DIR --host=

Create a database user with the command:

CREATE USER username WITH PASSWORD 'password';

Where username is a username and password is a strong password.

Once you create the user, you can log into the CockroachDB web interface at http://SERVER_IP:8080 (Where SERVER_IP is the IP address of cockroachdbcontrol) and log into the service with the username and password you created in the CockroachDB shell. Once logged in, you can start managing databases from the user-friendly web-based interface (Figure C)


Figure C: The CockroachDB web interface.

Ready to roll

And that's all there is to setting up a CockroachDB cluster. Your scalable database is now ready to roll. With the help of the web-interface, you can create and manage your databases and your cluster with ease.

Also see