Deploy a production CockroachDB cluster on three separate Ubuntu hosts (or three independent failure domains), not three processes on one server. Install the same CockroachDB release everywhere, give each node its own data store and listening addresses, use one identical three-address join list, secure communication with certificates whose SANs contain every production DNS name and IP, and initialize the cluster exactly once. Then verify SQL writes and reads through more than one node, inspect the HTTPS DB Console, and run the service under a manager such as systemd.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
What the finished deployment looks like
A three-node cluster has three independently reachable Ubuntu machines or virtual machines. Each machine runs one CockroachDB process and stores its own replicas. The nodes communicate over the SQL/RPC port (the examples use 26257) and expose the DB Console over HTTP(S) (the examples use 8080). Every node knows the same three addresses in its --join list, but its --store, --listen-addr, and --http-addr identify only that node.
As an Amazon Associate I earn from qualifying purchases.
Separate hosts are a production requirement, not merely a performance preference. Cockroach Labs states: “Note that running multiple nodes on a single host is useful for testing CockroachDB, but it’s not suitable for production.” Three processes on one Ubuntu server can help you learn the commands, but a host failure would remove every node and its intended fault tolerance.
| Arrangement | Use it for | Production status |
|---|---|---|
| Three separate Ubuntu hosts or independent failure domains | Production availability and replica placement | Appropriate topology |
| Three VMs or processes on one physical host | Command and application testing | Test only; one host failure removes the cluster |
Plan names, addresses, and network access first
Choose stable DNS names or IP addresses that every node can resolve and reach. The examples below use node1.example, node2.example, and node3.example. Replace them with names from your environment; do not leave the example names in a real certificate or service command.
#1 Best Overall
Use a complete address plan
- Assign one unique SQL/RPC listen address per host, such as
node1.example:26257. - Assign one unique DB Console address per host, such as
node1.example:8080. - Use the same three SQL/RPC addresses in the
--joinoption on all nodes. - If clients or an administrator will connect through a load balancer, include that DNS name and every relevant IP address in the node certificate SANs.
- Allow the required SQL/RPC and DB Console traffic between the hosts and from approved client networks. Keep management and database traffic restricted by your network controls.
For a single-region three-node cluster, a three-address join list is the normal pattern. CockroachDB’s deployment guidance notes that three to five join addresses are appropriate when planning a deployment; the important property is that a new or restarting node can reach several existing nodes rather than depending on one address.
Decide where each node’s data lives
Give every host a dedicated, persistent directory. The commands in this guide use /var/lib/cockroach/data for the store and /var/lib/cockroach/certs for certificates. Create the directories with ownership and permissions that allow only the CockroachDB service account and approved administrators to read private keys.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsInstall the same CockroachDB release on all three hosts
Install the Linux CockroachDB binary on node1, node2, and node3 using the current Linux installation instructions for the release you have selected. The package, archive, and checksum details are release-specific, so obtain them from CockroachDB’s authoritative Linux installation page at implementation time rather than mixing instructions from different versions.
Keep the binary and configuration under controlled administration. Before starting a node, check that all three hosts run the same release and that each host can resolve and reach the other two hosts on the SQL/RPC and DB Console ports required by your topology. A version mismatch or blocked port can look like a certificate or initialization failure later.
Create the TLS certificate hierarchy
A secure deployment uses a certificate authority (CA), node certificates, and client certificates. Protect the CA private key more carefully than the node keys: it is the authority used to issue replacement credentials. The secure workflow below creates a CA, one node certificate covering all three example node names, and a client certificate for the SQL administrator.
mkdir certs my-safe-directory
cockroach cert create-ca
--certs-dir=certs
--ca-key=my-safe-directory/ca.key
cockroach cert create-node node1.example node2.example node3.example
--certs-dir=certs
--ca-key=my-safe-directory/ca.key
cockroach cert create-client root
--certs-dir=certs
--ca-key=my-safe-directory/ca.keyUnderstand the files and their jobs
ca.crtis the CA certificate that lets nodes and clients verify the issuing authority.node.crtandnode.keyidentify a CockroachDB node and secure node-to-node communication.client.node.crtandclient.node.keyare client credentials; the example creates credentials for therootSQL user.
For production, the node certificate must contain every DNS name and IP address used to reach the node. These values are certificate Subject Alternative Names (SANs). Include the node’s normal hostname, any alternate name used by automation, and any load-balancer name or address that terminates or forwards connections to that node. A certificate that is valid for node1.example but not for the IP or alternate name a client actually uses will fail hostname verification.
Distribute credentials without distributing the CA key
Place the CA certificate and the appropriate node certificate and key on each corresponding host. Copy the client certificate and key only to the administrators or application systems that need SQL access. Keep my-safe-directory/ca.key in a protected administrative location; it does not need to be present on every database server after certificates are issued. Set restrictive permissions on every private key and document how you will revoke or replace credentials if a host or administrator account is compromised.
Start each node with its own store and address
Start CockroachDB on each host with the secure certificate directory, a unique store, unique SQL/RPC and DB Console addresses, and the identical join list. Run the following representative command on node1:
cockroach start
--certs-dir=/var/lib/cockroach/certs
--store=/var/lib/cockroach/data
--listen-addr=node1.example:26257
--http-addr=node1.example:8080
--join=node1.example:26257,node2.example:26257,node3.example:26257On node2, use its own store and addresses while retaining the same join list:
cockroach start
--certs-dir=/var/lib/cockroach/certs
--store=/var/lib/cockroach/data
--listen-addr=node2.example:26257
--http-addr=node2.example:8080
--join=node1.example:26257,node2.example:26257,node3.example:26257On node3:
cockroach start
--certs-dir=/var/lib/cockroach/certs
--store=/var/lib/cockroach/data
--listen-addr=node3.example:26257
--http-addr=node3.example:8080
--join=node1.example:26257,node2.example:26257,node3.example:26257The --store path must not be shared between hosts. A shared filesystem or a copied store would defeat the intended node identity and can corrupt an installation. The join list is a discovery list, not a directive to use one node’s data directory.
Do not use insecure mode for a reachable production cluster
The --insecure option disables network encryption and authentication. It is intended for local testing and must not be exposed on a routable production network. If you started an insecure test cluster, stop it and rebuild or reconfigure it with the certificate workflow before allowing production traffic.
Initialize the cluster exactly once
Wait until all three processes are running and can reach one another. Then initialize the cluster one time from any host, using any address in the join list:
cockroach init
--certs-dir=/var/lib/cockroach/certs
--host=node1.example:26257A successful command prints:
Cluster successfully initializedInitialization creates the cluster’s initial state; it is not a per-node step. Do not run cockroach init again against an already initialized cluster. If the command reports that the cluster is already initialized, leave the existing cluster state intact and proceed to connectivity checks instead of trying other nodes repeatedly.
Verify SQL connectivity and replicated data
Use the client certificate created for the administrative SQL user to connect:
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →cockroach sql
--certs-dir=/var/lib/cockroach/certs
--host=node1.example:26257Perform a small write/read test that is easy to identify and remove later:
CREATE DATABASE deployment_check;
USE deployment_check;
CREATE TABLE checks (id INT PRIMARY KEY, note STRING);
INSERT INTO checks VALUES (1, 'three-node deployment');
SELECT * FROM checks;Exit, connect through node2 or node3, and run the read again:
cockroach sql
--certs-dir=/var/lib/cockroach/certs
--host=node2.example:26257
--execute="SELECT * FROM deployment_check.checks;"Every node can act as a SQL gateway, so a successful read through another node demonstrates client routing beyond the first connection. It does not, by itself, prove that every replica is healthy; use the DB Console and replica information for that.
Check the DB Console over HTTPS
Open the DB Console at the HTTPS address for one of the nodes and confirm that three live nodes appear. Inspect the cluster and replication views for consistent replica counts. The walkthrough uses identical replica counts as evidence that data is replicated through CockroachDB’s Raft consensus protocol. Investigate a missing node, unavailable range, or differing replica state before declaring the deployment healthy.
Recommended Free Tools
Create a non-root administrative user
The initial root client certificate is useful for setup, but routine operations should use a named SQL user with only the roles required for console access and administration. Create that user and grant the minimum documented privileges for the tasks it must perform. Store its client credentials separately from the CA key, and test the account through the same network path that operators will use.
Put the process under systemd or another service manager
Do not rely on an interactive shell for a production database. Create a service definition for the CockroachDB account that invokes the same secure cockroach start arguments used during testing. Configure it to start after the network is available, restart after an unexpected process exit, and write logs to the location your operators monitor. Ensure the service account can read the certificate directory and write the store, but cannot modify the CA private-key archive.
Before enabling automatic startup, stop any manually launched copy of the process so systemd does not compete for the same store or ports. Start one service at a time, confirm the node appears in the DB Console, and then enable the service at boot on all three hosts. Retain the exact command-line configuration in your change records so a replacement host can be rebuilt consistently.
Production readiness checklist
- Topology: three separate Ubuntu hosts or failure domains, with persistent local stores.
- Software: identical CockroachDB release and controlled binary installation on every host.
- Networking: stable DNS or IP addresses, bidirectional node reachability, and approved SQL/RPC and DB Console access.
- Certificates: protected CA key; correct
ca.crt, node, and client files; every production DNS name, IP, and load-balancer address present in SANs. - Startup: unique store and listen addresses per node; one common join list.
- Initialization: one successful
cockroach init, never repeated on the initialized cluster. - Validation: SQL write/read test through more than one node and three live nodes visible in the HTTPS DB Console.
- Operations: systemd or another process manager, restart and log handling, documented certificate replacement, and monitoring/alerting based on the official production checklist.
- Privileges: routine administration through a non-root SQL user with only required roles.
Troubleshoot the failures that matter most
| Symptom | Likely cause | Action |
|---|---|---|
| TLS hostname or certificate verification error | The address used by the client is absent from the certificate SANs, or the wrong CA/certificate directory is selected. | Use the address covered by the certificate or issue node certificates containing every DNS name and IP used in production. Verify the client is pointing at the intended --certs-dir. |
| A node cannot join or remains unavailable | DNS resolution, firewall rules, blocked SQL/RPC port, incorrect listen address, or a join address that the node cannot reach. | Check name resolution and connectivity between every pair of hosts, then compare each node’s listen address and common join list. |
cockroach init cannot contact the cluster |
One or more nodes are stopped, certificates are unreadable, or the host argument is not reachable. | Confirm all three secure processes are running, verify key and certificate permissions, and retry against a reachable join address only after fixing the underlying issue. |
| “Cluster already initialized” appears | Initialization was previously completed. | Do not initialize again. Connect with cockroach sql and continue verification. |
| Only one node appears in the DB Console | Other processes have not joined, cannot communicate, or are using an incorrect address/certificate. | Review each node’s logs, network reachability, SAN coverage, and identical join list; then verify the node count again. |
Production traffic is running with --insecure |
The test configuration was promoted without TLS. | Remove it from the routable path and redeploy with a CA, node certificates, and client certificates before accepting production connections. |
Choose an operating model deliberately
The deployment commands above describe a self-managed installation. CockroachDB also documents cloud and on-premises deployment paths. The right choice depends on who owns host maintenance, certificates, upgrades, monitoring, and failure recovery.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware match| Decision | Self-managed three-node Ubuntu | Managed or orchestrated alternative |
|---|---|---|
| Compute | You provision and patch three Ubuntu machines or VMs and select their failure domains. | A cloud service or orchestrator supplies the underlying scheduling and host lifecycle. |
| Certificates | You generate and protect the CockroachDB CA and distribute node/client credentials. | The platform may automate certificate issuance; confirm SAN, rotation, and access behavior before relying on it. |
| Process lifecycle | You configure systemd (or an equivalent manager), restart behavior, and logs. | The platform manages processes and rollout mechanics, but you still need health checks and alert review. |
| Failure domains | You must place hosts so one physical or virtual failure does not remove all nodes. | Placement may be automated, but verify the actual zones or domains used by the service. |
For self-managed Ubuntu VMs, CockroachDB’s manual-deployment material includes guides for on-premises environments and several major cloud providers. Treat provider-specific networking, storage, and availability-zone settings as separate implementation work; the three-node certificate, join, initialization, and verification sequence remains the same.
What to do after the first successful check
Remove or isolate the temporary deployment_check database when its result is no longer needed. Record the node addresses, certificate inventory, service definition, and recovery contacts. Add monitoring and alerting from the production checklist, watch node liveness and replica health, and rehearse replacing a node or certificate before an outage forces you to discover missing procedures.
When adding application traffic, use the approved client certificate and the least-privileged SQL user rather than the setup account. Keep the three-node join list available for rebuilds, but do not treat it as a substitute for backups, alerting, or a tested recovery plan.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
