search

cockroachdb / docs

CockroachDB user documentation
https://cockroachlabs.com/docs
Creative Commons Attribution 4.0 International
190 stars 459 forks source link

refactor local Docker tutorial to run a single-node cluster #6664

Open taroface opened 4 years ago

taroface commented 4 years ago

Ryan Kuo (taroface) commented:

Per @nvanbenschoten:

I recently noticed that all of our local Docker deployment documentation focuses on running a multi-node cluster. This seems backwards to me. It's my understanding that Docker is primarily used for locally testing containers that will eventually be deployed to production using an orchestration tool like k8s.

When testing locally, users don't care about replication or running a multi-CRDB cluster - they just want some database that they can test their app against. I think it would serve our customers well to replace/augment this local Docker documentation with the significantly easier instructions of getting up and running with a single node CRDB cluster in Docker.

This is especially true because our Dockerhub documentation is lacking: https://hub.docker.com/r/cockroachdb/cockroach.

The above technically also applies to our local Kubernetes docs, but is a lower priority since running a multi-node cluster vs. a single-node cluster introduces less friction in K8s than it does in Docker.

Jira Issue: DOC-443

Frank-D commented 2 years ago

Would be nice to include in the online cockroachdb guide some more installation precisions (specifically, for docker + single-node / insecure setup), such as the below instructions (at least, those are the ones I've used that worked for me, but I lost some time putting those together initially..):

  1. Install Docker (or validate docker is already installed with # docker version)
  2. Download CockroachDB docker image: # docker pull cockroachdb/cockroach:v21.2.3
  3. Start CockroachDB (docker image / container): 
    # docker run -d --name=cockroachdb --hostname=localhost -p 26257:26257 -p 26256:8080 -v "~/cockroach-data:/cockroach/cockroach-data" cockroachdb/cockroach:v21.2.3 start-single-node --insecure
  4. Access CockroachDB on the command line as 'root' user with: 
    # docker exec -it cockroachdb ./cockroach sql --insecure
  5. Execute your first few SQL queries, and enjoy CockroachDB on your local.

thanks