<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></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>
