Skip to main content
CockroachDB can be deployed across various platforms and environments, from local development to production clusters on cloud providers or on-premises infrastructure.

​
Deployment Options

CockroachDB offers several deployment strategies to match your infrastructure needs:

CockroachCloud

Fully managed CockroachDB service with automated operations

Kubernetes

Container orchestration for automated scaling and management

Manual Deployment

Direct installation on physical or virtual machines

Docker

Containerized deployment for development and testing

​
Single-Node Deployment

For development and testing, start a single-node cluster:
1

Download CockroachDB

Download the latest CockroachDB binary for your platform from the official releases.
2

Start the Node

cockroach start-single-node \
  --insecure \
  --store=path=/mnt/cockroach-data \
  --listen-addr=localhost:26257 \
  --http-addr=localhost:8080
The --insecure flag disables security for testing. Never use this in production.
3

Access the SQL Shell

cockroach sql --insecure --host=localhost:26257

​
Multi-Node Cluster

​
Manual Deployment on Multiple Machines

1

Start the First Node

cockroach start \
  --certs-dir=certs \
  --advertise-addr=<node1-address> \
  --join=<node1-address>,<node2-address>,<node3-address> \
  --cache=.25 \
  --max-sql-memory=.25 \
  --background
2

Start Additional Nodes

Repeat the start command on each node, adjusting --advertise-addr to each node’s address:
cockroach start \
  --certs-dir=certs \
  --advertise-addr=<node2-address> \
  --join=<node1-address>,<node2-address>,<node3-address> \
  --cache=.25 \
  --max-sql-memory=.25 \
  --background
3

Initialize the Cluster

From any node, run the init command once:
cockroach init --certs-dir=certs --host=<any-node-address>
Ensure all nodes can communicate with each other on port 26257. Configure your firewall rules accordingly.

​
Kubernetes Deployment

Deploy CockroachDB as a StatefulSet on Kubernetes for automated orchestration: 
apiVersion: v1
kind: Service
metadata:
  name: cockroachdb
  labels:
    app: cockroachdb
spec:
  ports:
  - port: 26257
    targetPort: 26257
    name: grpc
  - port: 8080
    targetPort: 8080
    name: http
  clusterIP: None
  selector:
    app: cockroachdb
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: cockroachdb
spec:
  serviceName: "cockroachdb"
  replicas: 3
  selector:
    matchLabels:
      app: cockroachdb
  template:
    metadata:
      labels:
        app: cockroachdb
    spec:
      containers:
      - name: cockroachdb
        image: cockroachdb/cockroach:latest
        ports:
        - containerPort: 26257
          name: grpc
        - containerPort: 8080
          name: http
        command:
          - "/bin/bash"
          - "-ecx"
          - |
            exec /cockroach/cockroach start \
            --logtostderr \
            --insecure \
            --advertise-host $(hostname -f) \
            --http-addr 0.0.0.0 \
            --join cockroachdb-0.cockroachdb,cockroachdb-1.cockroachdb,cockroachdb-2.cockroachdb \
            --cache 25% \
            --max-sql-memory 25%
        volumeMounts:
        - name: datadir
          mountPath: /cockroach/cockroach-data
  volumeClaimTemplates:
  - metadata:
      name: datadir
    spec:
      accessModes:
        - "ReadWriteOnce"
      resources:
        requests:
          storage: 100Gi

​
Deploy to Kubernetes

1

Apply the StatefulSet

kubectl apply -f cockroachdb-statefulset.yaml
2

Wait for Pods to Start

kubectl get pods -l app=cockroachdb
3

Initialize the Cluster

kubectl apply -f cluster-init.yaml
4

Access the SQL Client

kubectl run cockroachdb-client --rm -it \
  --image=cockroachdb/cockroach \
  --restart=Never \
  -- sql --insecure --host=cockroachdb-0.cockroachdb

​
Docker Deployment

For quick local development with Docker:
Docker Single Node
# Create a bridge network
docker network create -d bridge roachnet

# Start CockroachDB container
docker run -d \
  --name=roach1 \
  --hostname=roach1 \
  --net=roachnet \
  -p 26257:26257 \
  -p 8080:8080 \
  -v "roach1:/cockroach/cockroach-data" \
  cockroachdb/cockroach:latest \
  start-single-node --insecure

​
Multi-Node Docker Cluster

# Create network
docker network create -d bridge roachnet

# Start node 1
docker run -d \
  --name=roach1 \
  --hostname=roach1 \
  --net=roachnet \
  -p 26257:26257 -p 8080:8080 \
  -v "roach1:/cockroach/cockroach-data" \
  cockroachdb/cockroach:latest start \
  --insecure \
  --join=roach1,roach2,roach3

# Start node 2
docker run -d \
  --name=roach2 \
  --hostname=roach2 \
  --net=roachnet \
  -v "roach2:/cockroach/cockroach-data" \
  cockroachdb/cockroach:latest start \
  --insecure \
  --join=roach1,roach2,roach3

# Start node 3
docker run -d \
  --name=roach3 \
  --hostname=roach3 \
  --net=roachnet \
  -v "roach3:/cockroach/cockroach-data" \
  cockroachdb/cockroach:latest start \
  --insecure \
  --join=roach1,roach2,roach3

# Initialize cluster
docker exec -it roach1 \
  ./cockroach init --insecure

​
Cloud Provider Deployments

​
AWS Deployment Considerations

VPC Configuration

Create a VPC with subnets across multiple availability zones for high availability

Security Groups

Configure security groups to allow traffic on ports 26257 (inter-node) and 8080 (admin UI)

Instance Types

Use compute-optimized instances (c5, c6i) for better performance

Storage

Use EBS volumes with provisioned IOPS (io1/io2) for production workloads

​
GCP Deployment Considerations

  • Use Compute Engine instances with local SSDs for optimal performance
  • Deploy across multiple zones within a region for availability
  • Configure VPC firewall rules for node communication
  • Use persistent disks with SSD for cost-effective storage

​
Azure Deployment Considerations

  • Use Premium SSD managed disks for storage
  • Deploy across availability zones for redundancy
  • Configure Network Security Groups for traffic control
  • Use Ds-series or Fs-series VMs for optimal performance

​
Resource Requirements

Production deployments should follow these minimum recommendations:
  • CPU: 4+ cores per node
  • RAM: 16GB+ per node
  • Storage: SSD-backed storage with 500+ IOPS
  • Network: 1Gbps+ between nodes
  • Nodes: Minimum of 3 nodes for fault tolerance

​
Environment Variables

The Docker entrypoint script supports several environment variables: 
COCKROACH_DATABASE=defaultdb      # Default database name
COCKROACH_USER=myuser             # Create a default user
COCKROACH_PASSWORD=mypassword     # Set user password
COCKROACH_ARGS="start --insecure" # Pass custom arguments

​
Next Steps

Security Configuration

Configure certificates and authentication

Scaling

Learn how to scale your cluster

Backup & Restore

Set up backup strategies

Build docs developers (and LLMs) love

Get started for freeTalk to us