Knowledgebase

<div style="font-family: Arial, Helvetica, sans-serif; line-height: 1.6; color: #333;">

<h1>How to Install CockroachDB v25.3.3 on Ubuntu 24.04</h1>

<p>

This guide explains how to manually install and configure <strong>CockroachDB v25.3.3</strong>

on an Ubuntu 24.04 server. The steps below follow the same basic configuration used by the

CockroachDB Ansible deployment.

</p>

<div style="background:#fff3cd; border:1px solid #ffeeba; padding:15px; margin:20px 0; border-radius:5px;">

<strong>Important:</strong> This guide configures CockroachDB in

<strong>insecure single-node mode</strong>. This configuration is intended for testing,

development, or lab environments. Do not expose an insecure CockroachDB cluster to the

public Internet in a production environment.

</div>

<h2>1. Requirements</h2>

<p>Before beginning, make sure you have:</p>

<ul>

    <li>Ubuntu 24.04 LTS server</li>

    <li>Root or sudo access</li>

    <li>An active Internet connection</li>

    <li>At least one available server</li>

</ul>

<p>Log into your Ubuntu server using SSH.</p>

<pre><code>ssh username@SERVER_IP</code></pre>

<p>Replace <code>username</code> with your Ubuntu username and <code>SERVER_IP</code> with your server IP address.</p>

<h2>2. Update Ubuntu</h2>

<p>First, update the package information:</p>

<pre><code>sudo apt update</code></pre>

<p>Then upgrade the installed packages:</p>

<pre><code>sudo apt upgrade -y</code></pre>

<p>Wait for the upgrade to finish before continuing.</p>

<h2>3. Install Required Packages</h2>

<p>

Install the tools required to download, extract and run CockroachDB.

</p>

<pre><code>sudo apt install -y curl wget tar ntp unzip</code></pre>

<p>Verify that the required commands are available:</p>

<pre><code>curl --version

wget --version

tar --version

unzip -v</code></pre>

<h2>4. Configure Network Time Synchronisation</h2>

<p>

CockroachDB requires accurate system time. The configuration below follows the

same Google NTP server configuration used by the Ansible playbook.

</p>

<p>Disable Ubuntu's system time synchronisation:</p>

<pre><code>sudo timedatectl set-ntp no</code></pre>

<p>Stop the NTP service:</p>

<pre><code>sudo systemctl stop ntp</code></pre>

<p>Create a backup of the existing NTP configuration:</p>

<pre><code>sudo cp /etc/ntp.conf /etc/ntp.conf.bak</code></pre>

<p>Open the NTP configuration file:</p>

<pre><code>sudo nano /etc/ntp.conf</code></pre>

<p>Replace its contents with:</p>

<pre><code>driftfile /var/lib/ntp/ntp.drift

server time1.google.com iburst

server time2.google.com iburst

server time3.google.com iburst

server time4.google.com iburst</code></pre>

<p>Save the file:</p>

<ul>

    <li>Press <strong>Ctrl + O</strong></li>

    <li>Press <strong>Enter</strong></li>

    <li>Press <strong>Ctrl + X</strong></li>

</ul>

<p>Synchronise the server time:</p>

<pre><code>sudo ntpd -gq</code></pre>

<p>Start NTP again:</p>

<pre><code>sudo systemctl start ntp</code></pre>

<p>Enable NTP so that it starts automatically:</p>

<pre><code>sudo systemctl enable ntp</code></pre>

<p>Check the service:</p>

<pre><code>sudo systemctl status ntp --no-pager</code></pre>

<h2>5. Create the CockroachDB User</h2>

<p>

For security and easier service management, CockroachDB will run using a dedicated

Linux user instead of the root account.

</p>

<p>Create the user:</p>

<pre><code>sudo useradd -m -s /bin/bash cockroach</code></pre>

<p>Verify the user:</p>

<pre><code>id cockroach</code></pre>

<p>You should see information for the <code>cockroach</code> user.</p>

<h2>6. Create the CockroachDB Directory</h2>

<p>Create the main CockroachDB directory:</p>

<pre><code>sudo mkdir -p /var/lib/cockroach</code></pre>

<p>Give the directory to the CockroachDB user:</p>

<pre><code>sudo chown -R cockroach:cockroach /var/lib/cockroach</code></pre>

<p>Set the directory permissions:</p>

<pre><code>sudo chmod 755 /var/lib/cockroach</code></pre>

<h2>7. Download CockroachDB v25.3.3</h2>

<p>Move to the temporary directory:</p>

<pre><code>cd /tmp</code></pre>

<p>Download the CockroachDB v25.3.3 Linux AMD64 archive:</p>

<pre><code>sudo wget -O cockroach.tgz \

https://binaries.cockroachdb.com/cockroach-v25.3.3.linux-amd64.tgz</code></pre>

<p>Check that the download exists:</p>

<pre><code>ls -lh /tmp/cockroach.tgz</code></pre>

<h2>8. Extract CockroachDB</h2>

<p>Extract the downloaded archive:</p>

<pre><code>sudo tar -xzf /tmp/cockroach.tgz -C /tmp</code></pre>

<p>Check the extracted directory:</p>

<pre><code>ls -lah /tmp/cockroach-v25.3.3.linux-amd64</code></pre>

<p>You should see the <code>cockroach</code> executable.</p>

<h2>9. Install the CockroachDB Binary</h2>

<p>Copy the CockroachDB binary into the system executable directory:</p>

<pre><code>sudo cp /tmp/cockroach-v25.3.3.linux-amd64/cockroach /usr/local/bin/cockroach</code></pre>

<p>Make the binary executable:</p>

<pre><code>sudo chmod 755 /usr/local/bin/cockroach</code></pre>

<h2>10. Verify the CockroachDB Installation</h2>

<p>Run:</p>

<pre><code>cockroach version</code></pre>

<p>

You should see version information containing:

</p>

<pre><code>v25.3.3</code></pre>

<p>If the command is not found, check the binary:</p>

<pre><code>ls -lh /usr/local/bin/cockroach</code></pre>

<h2>11. Create the Certificates Directory</h2>

<p>

The Ansible deployment creates a certificates directory. Create it manually with:

</p>

<pre><code>sudo mkdir -p /var/lib/cockroach/certs</code></pre>

<p>Set ownership:</p>

<pre><code>sudo chown -R cockroach:cockroach /var/lib/cockroach/certs</code></pre>

<p>Set permissions:</p>

<pre><code>sudo chmod 755 /var/lib/cockroach/certs</code></pre>

<h2>12. Create the CockroachDB Data Directory</h2>

<p>Create the database storage directory:</p>

<pre><code>sudo mkdir -p /var/lib/cockroach/cockroach-data</code></pre>

<p>Set the correct owner:</p>

<pre><code>sudo chown -R cockroach:cockroach /var/lib/cockroach/cockroach-data</code></pre>

<p>Set permissions:</p>

<pre><code>sudo chmod 755 /var/lib/cockroach/cockroach-data</code></pre>

<h2>13. Create the systemd Service</h2>

<p>

Creating a systemd service allows CockroachDB to start automatically when Ubuntu boots.

</p>

<p>Open a new service file:</p>

<pre><code>sudo nano /etc/systemd/system/cockroach.service</code></pre>

<p>Paste the following:</p>

<pre><code>[Unit]

Description=CockroachDB

After=network.target

[Service]

Type=simple

User=cockroach

WorkingDirectory=/var/lib/cockroach

ExecStart=/usr/local/bin/cockroach start-single-node \

  --insecure \

  --store=/var/lib/cockroach/cockroach-data \

  --listen-addr=0.0.0.0:26257 \

  --http-addr=0.0.0.0:8082

Restart=always

RestartSec=5

[Install]

WantedBy=multi-user.target</code></pre>

<p>Save the file:</p>

<ul>

    <li>Press <strong>Ctrl + O</strong></li>

    <li>Press <strong>Enter</strong></li>

    <li>Press <strong>Ctrl + X</strong></li>

</ul>

<h2>14. Reload systemd</h2>

<p>Tell systemd about the new CockroachDB service:</p>

<pre><code>sudo systemctl daemon-reload</code></pre>

<h2>15. Enable CockroachDB</h2>

<p>Configure CockroachDB to start automatically when the server boots:</p>

<pre><code>sudo systemctl enable cockroach</code></pre>

<h2>16. Start CockroachDB</h2>

<p>Start the service:</p>

<pre><code>sudo systemctl start cockroach</code></pre>

<h2>17. Check CockroachDB Status</h2>

<p>Check whether the service is running:</p>

<pre><code>sudo systemctl status cockroach --no-pager</code></pre>

<p>Look for:</p>

<pre><code>Active: active (running)</code></pre>

<p>If you see <strong>active (running)</strong>, CockroachDB has started successfully.</p>

<h2>18. Verify Port 26257</h2>

<p>

CockroachDB uses port <strong>26257</strong> for SQL and cluster communication in this configuration.

</p>

<p>Check whether the port is listening:</p>

<pre><code>sudo ss -lntp | grep 26257</code></pre>

<p>You should see a listening socket containing:</p>

<pre><code>:26257</code></pre>

<h2>19. Verify the CockroachDB Web Interface</h2>

<p>

The CockroachDB HTTP interface is configured to use port <strong>8082</strong>.

</p>

<p>Check the port:</p>

<pre><code>sudo ss -lntp | grep 8082</code></pre>

<p>

If the server firewall allows the port, open a browser and visit:

</p>

<pre><code>http://SERVER_IP:8082</code></pre>

<p>

Replace <code>SERVER_IP</code> with the IP address of your Ubuntu server.

</p>

<h2>20. Test the CockroachDB SQL Connection</h2>

<p>Run:</p>

<pre><code>sudo -u cockroach /usr/local/bin/cockroach sql \

--insecure \

--host=127.0.0.1:26257</code></pre>

<p>If successful, you should see a CockroachDB SQL prompt.</p>

<p>For example:</p>

<pre><code>root@127.0.0.1:26257/defaultdb&gt;</code></pre>

<p>Run a simple test:</p>

<pre><code>SELECT version();</code></pre>

<p>Then exit the SQL shell:</p>

<pre><code>\q</code></pre>

<h2>21. Check the CockroachDB Service</h2>

<p>For a final service check, run:</p>

<pre><code>sudo systemctl is-active cockroach</code></pre>

<p>The expected result is:</p>

<pre><code>active</code></pre>

<p>You can also check whether the service is enabled:</p>

<pre><code>sudo systemctl is-enabled cockroach</code></pre>

<p>The expected result is:</p>

<pre><code>enabled</code></pre>

<h2>22. Useful CockroachDB Commands</h2>

<p>Check the installed version:</p>

<pre><code>cockroach version</code></pre>

<p>Check the service:</p>

<pre><code>sudo systemctl status cockroach</code></pre>

<p>Restart CockroachDB:</p>

<pre><code>sudo systemctl restart cockroach</code></pre>

<p>Stop CockroachDB:</p>

<pre><code>sudo systemctl stop cockroach</code></pre>

<p>Start CockroachDB:</p>

<pre><code>sudo systemctl start cockroach</code></pre>

<p>View recent CockroachDB service logs:</p>

<pre><code>sudo journalctl -u cockroach -n 50 --no-pager</code></pre>

<p>View live CockroachDB logs:</p>

<pre><code>sudo journalctl -u cockroach -f</code></pre>

<h2>23. Final Verification Checklist</h2>

<p>Before considering the installation complete, verify the following:</p>

<ul>

    <li>CockroachDB version reports <strong>v25.3.3</strong>.</li>

    <li>The <code>cockroach</code> Linux user exists.</li>

    <li>The <code>/var/lib/cockroach</code> directory exists.</li>

    <li>The <code>/var/lib/cockroach/cockroach-data</code> directory exists.</li>

    <li>The CockroachDB systemd service is enabled.</li>

    <li>The CockroachDB systemd service is running.</li>

    <li>Port <strong>26257</strong> is listening.</li>

    <li>Port <strong>8082</strong> is listening.</li>

    <li>The SQL connection works using the CockroachDB client.</li>

    <li>The CockroachDB web interface can be accessed at <code>http://SERVER_IP:8082</code> if the firewall/network allows it.</li>

</ul>

<h2>24. Troubleshooting</h2>

<h3>CockroachDB service will not start</h3>

<p>Run:</p>

<pre><code>sudo systemctl status cockroach --no-pager -l</code></pre>

<p>Then:</p>

<pre><code>sudo journalctl -u cockroach -n 100 --no-pager</code></pre>

<h3>Port 26257 is already in use</h3>

<p>Check which process is using the port:</p>

<pre><code>sudo ss -lntp | grep 26257</code></pre>

<h3>Port 8082 is already in use</h3>

<p>Check which process is using the port:</p>

<pre><code>sudo ss -lntp | grep 8082</code></pre>

<h3>CockroachDB command is not found</h3>

<p>Check whether the binary exists:</p>

<pre><code>ls -lh /usr/local/bin/cockroach</code></pre>

<p>Then test it directly:</p>

<pre><code>/usr/local/bin/cockroach version</code></pre>

<h3>SQL connection fails</h3>

<p>First check the service:</p>

<pre><code>sudo systemctl status cockroach --no-pager</code></pre>

<p>Then check port 26257:</p>

<pre><code>sudo ss -lntp | grep 26257</code></pre>

<p>Finally try:</p>

<pre><code>sudo -u cockroach /usr/local/bin/cockroach sql \

--insecure \

--host=127.0.0.1:26257</code></pre>

<h2>Installation Complete</h2>

<p>

CockroachDB v25.3.3 is installed as a single-node systemd service on Ubuntu 24.04.

The database service uses port <strong>26257</strong>, while the CockroachDB HTTP

interface uses port <strong>8082</strong>.

</p>

<div style="background:#f8d7da; border:1px solid #f5c6cb; padding:15px; margin:20px 0; border-radius:5px;">

<strong>Security warning:</strong> This configuration uses the

<code>--insecure</code> option. It does not provide the security protections expected

for a production database deployment. For production use, configure CockroachDB with

secure certificates and authentication and restrict database ports using your firewall.

</div>

<p>

<strong>Expected services:</strong>

</p>

<ul>

    <li>SQL / cluster port: <strong>26257</strong></li>

    <li>HTTP administration interface: <strong>8082</strong></li>

    <li>Linux service user: <strong>cockroach</strong></li>

    <li>Data directory: <strong>/var/lib/cockroach/cockroach-data</strong></li>

    <li>Installation directory: <strong>/usr/local/bin/cockroach</strong></li>

</ul>

</div>