Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[DOC-10949] Update Docker instructions for Cloud-first #18839

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

[DOC-10949] Update Docker instructions for Cloud-first #18839

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ebe0c07
[DOC-10949] Update Docker instructions for Cloud-first
mdlinville Aug 19, 2024
78aba0e
Apply suggestions from code review
mdlinville Aug 20, 2024
2dbcb11
Merge branch 'main' into DOC-10949
mdlinville Aug 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions src/current/_includes/v24.2/install-docker-steps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
{% comment %}This include is used in install-cockroachdb-*.md{% endcomment %}
{% capture deployment_link %}
{% if page.name contains "mac" %}[Deploy a local container in Docker]({% link {{ page.version.version }}/start-a-local-cluster-in-docker-mac.md %})
{% elsif page.name contains "windows" %}[Deploy a local container in Docker]({% link {{ page.version.version }}/start-a-local-cluster-in-docker-windows.md %})
{% else %}[Deploy a local container in Docker]({% link {{ page.version.version }}/start-a-local-cluster-in-docker-linux.md %})
{% endif %}
{% endcapture %}

{{site.data.alerts.callout_danger}}
Running a stateful application like CockroachDB in Docker is more complex and error-prone than most uses of Docker. Unless you are very experienced with Docker, we recommend starting with a different installation and deployment method.
{{site.data.alerts.end}}

CockroachDB's Docker images are [multi-platform images](https://docs.docker.com/build/building/multi-platform/) that contain binaries for both Intel and ARM. Multi-platform images do not take up additional space on your Docker host.

Experimental images are not qualified for production use and not eligible for support or uptime SLA commitments.

1. Install a container runtime, such as [Docker Desktop](https://www.docker.com/products/docker-desktop/).
1. Verify that the runtime service is installed correctly and running in the background. Refer to the runtime's documentation. For Docker, start a terminal and run `docker version`. If you get an error, verify your installation and try again.
1. Visit [Docker Hub](https://hub.docker.com/r/cockroachdb/cockroach) and decide which image tag to pull. Releases are rolled out gradually. Docker images for a new release are published when other binary artifacts are published. The following tag formats are commonly used; other tags are available.

<table markdown="1">
<thead>
<tr>
<td>Tag</td>
<td>Example</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>An exact patch</td>
<td>`{{ page.version.name }}`</td>
<td>Pins a cluster to an exact patch. The cluster is upgraded to a newer patch or major version only when you pull a newer tag.</td>
</tr>
<tr>
<td>Latest patch within a major version</td>
<td>`latest-{{ page.version.version }}`</td>
<td>Automatically updates a cluster to the latest patch of the version you specify. This tag is recommended in production, because it keeps your cluster updated within a major version but does not automatically upgrade your cluster to a new major version.</td>
</tr>
<tr>
<td>`latest`</td>
<td>The latest patch within the latest major version.
<td>This is the default if you do not specify a tag. It updates your cluster automatically to each new patch and major version, and is not recommended in production.</td>
</tr>
</tbody>
</table>

Copy the tag you want to pull.

1. Pull the image. Replace `{TAG}` with the tag from the previous step.

{% include_cached copy-clipboard.html %}
~~~ shell
docker pull cockroachdb/cockroach:{TAG}
~~~

1. Start a cluster by starting the container on each node using `docker start`. The default command is `cockroach start`. Pass your desired flags as the final argument. For details, refer to {{ deployment_link | strip }}.
41 changes: 3 additions & 38 deletions src/current/v24.2/install-cockroachdb-linux.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,46 +114,11 @@ true
</ul>
</div>

<div id="use-docker-linux" class="install-option">
<h2 id="install-docker">Use Docker</h2>
<div id="use-docker-linux" markdown="1" class="install-option">
<h2 id="install-docker">Use Docker</h2>

{{site.data.alerts.callout_danger}}Running a stateful application like CockroachDB in Docker is more complex and error-prone than most uses of Docker. Unless you are very experienced with Docker, we recommend starting with a different installation and deployment method.{{site.data.alerts.end}}
{% include {{ page.version.version }}/install-docker-steps.md %}

<p>For CockroachDB v22.2.beta-5 and above, Docker images are <a href="https://docs.docker.com/build/building/multi-platform/">multi-platform images</a> that contain binaries for both Intel and ARM. Multi-platform images do not take up additional space on your Docker host.</p>
<p>Docker images for previous releases contain Intel binaries only. Intel binaries can run on ARM systems, but with a significant reduction in performance.</p>
<p>CockroachDB on ARM is in <b><a href="https://www.cockroachlabs.com/docs/stable/cockroachdb-feature-availability#feature-availability-phases">Limited Access</a></b> in v22.2.13, and is <b>experimental</b> in all other versions. Experimental images are not qualified for production use and not eligible for support or uptime SLA commitments.</p>

<ol>
<li>
<p>Install <a href="https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/">Docker for Linux</a>. Please carefully check that you meet all prerequisites.</p>
</li>
<li>
<p>Confirm that the Docker daemon is running in the background:</p>

<div class="copy-clipboard">
<svg data-eventcategory="linux-docker-button" id="copy-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 12 12"><style>.st0{fill:#A2A2A2;}</style><title>icon/buttons/copy</title><g id="Mask"><path id="path-1_1_" class="st0" d="M4.9 4.9v6h6v-6h-6zM3.8 3.8H12V12H3.8V3.8zM2.7 7.1v1.1H.1S0 5.5 0 0h8.2v2.7H7.1V1.1h-6v6h1.6z"/></g></svg>
<svg id="copy-check" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 12 10"><style>.st1{fill:#54B30E;}</style><path id="path-1_2_" class="st1" d="M3.8 9.1c-.3 0-.5-.1-.6-.2L.3 6C0 5.7-.1 5.2.2 4.8c.3-.4.9-.4 1.3-.1L3.8 7 10.6.2c.3-.3.9-.4 1.2 0 .3.3.3.9 0 1.2L4.4 8.9c-.2.1-.4.2-.6.2z"/></svg>
</div>
<div class="highlight"><pre class="highlight"><code data-eventcategory="linux-docker-step2"><span class="nv language-shell linux-docker-step2" id="linux-docker-step2-{{ page.version.version }}" data-eventcategory="linux-docker-step2">$ </span>docker version</code></pre></div>
<p>If you do not see the server listed, start the <strong>Docker</strong> daemon.</p>

{{site.data.alerts.callout_info}}On Linux, Docker needs sudo privileges.{{site.data.alerts.end}}
</li>
<li>
<p>Pull the image for the {{page.release_info.version}} release of CockroachDB from <a href="https://hub.docker.com/r/{{page.release_info.docker_image}}/" class="linux-docker-step3" id="linux-docker-step3-{{page.version.version}}" data-eventcategory="linux-docker-step3">Docker Hub</a>:</p>

<div class="copy-clipboard">
<svg data-eventcategory="linux-docker-button" id="copy-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 12 12"><style>.st0{fill:#A2A2A2;}</style><title>icon/buttons/copy</title><g id="Mask"><path id="path-1_1_" class="st0" d="M4.9 4.9v6h6v-6h-6zM3.8 3.8H12V12H3.8V3.8zM2.7 7.1v1.1H.1S0 5.5 0 0h8.2v2.7H7.1V1.1h-6v6h1.6z"/></g></svg>
<svg id="copy-check" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 12 10"><style>.st1{fill:#54B30E;}</style><path id="path-1_2_" class="st1" d="M3.8 9.1c-.3 0-.5-.1-.6-.2L.3 6C0 5.7-.1 5.2.2 4.8c.3-.4.9-.4 1.3-.1L3.8 7 10.6.2c.3-.3.9-.4 1.2 0 .3.3.3.9 0 1.2L4.4 8.9c-.2.1-.4.2-.6.2z"/></svg>
</div>
<div class="highlight"><pre class="highlight"><code data-eventcategory="linux-docker-step3"><span class="nv language-shell linux-docker-step3" id="linux-docker-step3-{{ page.version.version }}" data-eventcategory="linux-docker-step3">$ </span>sudo docker pull {{page.release_info.docker_image}}:{{page.release_info.version}}</code></pre>
</div>
</li>
<li>
<p>Keep up-to-date with CockroachDB releases and best practices:</p>
{% include marketo-install.html uid="2" %}
</li>
</ol>
</div>

<div id="build-from-source-linux" class="install-option">
Expand Down
39 changes: 3 additions & 36 deletions src/current/v24.2/install-cockroachdb-mac.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,6 @@ docs_area: deploy

{% capture arch_note_binaries %}<p>For CockroachDB v22.2.x and above, download the binaries for your system architecture, either Intel or ARM (<a href="https://support.apple.com/en-us/HT211814">Apple Silicon</a>).</p><p>For previous releases, download Intel binaries. Intel binaries can run on ARM systems, but with a significant reduction in performance. CockroachDB on ARM for macOS is <b>experimental</b> and is not yet qualified for production use and not eligible for support or uptime SLA commitments.</p>{% endcapture %}

{% capture arch_note_docker %}<p>For CockroachDB v22.2.beta-5 and above, Docker images are <a href="https://docs.docker.com/build/building/multi-platform/">multi-platform images</a> that contain binaries for both Intel and ARM (<a href="https://support.apple.com/HT211814">Apple Silicon</a>). Multi-platform images do not take up additional space on your Docker host.</p><p>Docker images for previous releases contain Intel binaries only. Intel binaries can run on ARM systems, but with a significant reduction in performance.</p><p>CockroachDB on ARM for macOS is <b>experimental</b> and is not yet qualified for production use and not eligible for support or uptime SLA commitments.</p>{% endcapture %}

{{site.data.alerts.callout_info}}
CockroachDB on macOS is experimental and not suitable for production deployments.
{{site.data.alerts.end}}
Expand Down Expand Up @@ -172,42 +170,11 @@ true
<p>To orchestrate CockroachDB locally using <a href="https://kubernetes.io/">Kubernetes</a>, either with configuration files or the <a href="https://helm.sh/">Helm</a> package manager, see <a href="orchestrate-a-local-cluster-with-kubernetes.html">Orchestrate CockroachDB Locally with Minikube</a>.</p>
</div>

<div id="use-docker" class="install-option">
<h2 id="install-docker">Use Docker</h2>

{{site.data.alerts.callout_danger}}Running a stateful application like CockroachDB in Docker is more complex and error-prone than most uses of Docker. Unless you are very experienced with Docker, we recommend starting with a different installation and deployment method.{{site.data.alerts.end}}

{{ arch_note_docker }}
<div id="use-docker" markdown="1" class="install-option">
<h2 id="install-docker">Use Docker</h2>

<ol>
<li>
<p>Install <a href="https://docs.docker.com/docker-for-mac/install/">Docker for Mac</a>. Please carefully check that you meet all prerequisites.</p>
</li>
<li>
<p>Confirm that the Docker daemon is running in the background:</p>

<div class="copy-clipboard">
<svg data-eventcategory="mac-docker-button" id="copy-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 12 12"><style>.st0{fill:#A2A2A2;}</style><title>icon/buttons/copy</title><g id="Mask"><path id="path-1_1_" class="st0" d="M4.9 4.9v6h6v-6h-6zM3.8 3.8H12V12H3.8V3.8zM2.7 7.1v1.1H.1S0 5.5 0 0h8.2v2.7H7.1V1.1h-6v6h1.6z"/></g></svg>
<svg id="copy-check" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 12 10"><style>.st1{fill:#54B30E;}</style><path id="path-1_2_" class="st1" d="M3.8 9.1c-.3 0-.5-.1-.6-.2L.3 6C0 5.7-.1 5.2.2 4.8c.3-.4.9-.4 1.3-.1L3.8 7 10.6.2c.3-.3.9-.4 1.2 0 .3.3.3.9 0 1.2L4.4 8.9c-.2.1-.4.2-.6.2z"/></svg>
</div>
<div class="highlight"><pre class="highlight"><code data-eventcategory="mac-docker-step2"><span class="nv language-shell mac-docker-step2" id="mac-docker-step2-{{ page.version.version }}" data-eventcategory="mac-docker-step2">$ </span>docker version</code></pre></div>
<p>If you do not see the server listed, start the <strong>Docker</strong> daemon.</p>
</li>
<li>
<p>Pull the image for the {{page.release_info.version}} release of CockroachDB from <a href="https://hub.docker.com/r/{{page.release_info.docker_image}}/" class="mac-docker-step3" id="mac-docker-step3-{{page.version.version}}" data-eventcategory="mac-docker-step3">Docker Hub</a>:</p>
{% include {{ page.version.version }}/install-docker-steps.md %}

<div class="copy-clipboard">
<svg data-eventcategory="mac-docker-button" id="copy-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 12 12"><style>.st0{fill:#A2A2A2;}</style><title>icon/buttons/copy</title><g id="Mask"><path id="path-1_1_" class="st0" d="M4.9 4.9v6h6v-6h-6zM3.8 3.8H12V12H3.8V3.8zM2.7 7.1v1.1H.1S0 5.5 0 0h8.2v2.7H7.1V1.1h-6v6h1.6z"/></g></svg>
<svg id="copy-check" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 12 10"><style>.st1{fill:#54B30E;}</style><path id="path-1_2_" class="st1" d="M3.8 9.1c-.3 0-.5-.1-.6-.2L.3 6C0 5.7-.1 5.2.2 4.8c.3-.4.9-.4 1.3-.1L3.8 7 10.6.2c.3-.3.9-.4 1.2 0 .3.3.3.9 0 1.2L4.4 8.9c-.2.1-.4.2-.6.2z"/></svg>
</div>
<div class="highlight"><pre class="highlight"><code data-eventcategory="mac-docker-step3"><span class="nv language-shell mac-docker-step3" id="mac-docker-step3-{{ page.version.version }}" data-eventcategory="mac-docker-step3">$ </span>docker pull {{page.release_info.docker_image}}:{{page.release_info.version}}</code></pre>
</div>
</li>
<li>
<p>Keep up-to-date with CockroachDB releases and best practices:</p>
{% include marketo-install.html uid="3" %}
</li>
</ol>
</div>

<div id="build-from-source" class="install-option">
Expand Down
38 changes: 3 additions & 35 deletions src/current/v24.2/install-cockroachdb-windows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,44 +56,12 @@ Use one of the options below to install CockroachDB. To upgrade an existing clus
To orchestrate CockroachDB locally using <a href="https://kubernetes.io/">Kubernetes</a>, either with configuration files or the <a href="https://helm.sh/">Helm</a> package manager, see <a href="orchestrate-a-local-cluster-with-kubernetes.html">Orchestrate CockroachDB Locally with Minikube</a>.
</section>

<section id="use-docker-windows" markdown="1" class="install-option">
<div id="use-docker-windows" markdown="1" class="install-option">
<h2 id="install-docker">Use Docker</h2>

{{site.data.alerts.callout_danger}}Running a stateful application like CockroachDB in Docker is more complex and error-prone than most uses of Docker. Unless you are very experienced with Docker, we recommend starting with a different installation and deployment method.{{site.data.alerts.end}}
{% include {{ page.version.version }}/install-docker-steps.md %}

For CockroachDB v22.2.beta-5 and above, Docker images are <a href="https://docs.docker.com/build/building/multi-platform/">multi-platform images</a> that contains binaries for both Intel and ARM. CockroachDB on ARM systems is <b>experimental</b> and is not yet qualified for production use and not eligible for support or uptime SLA commitments. Multi-platform images do not take up additional space on your Docker host.

Docker images for previous releases contain Intel binaries only. Intel binaries can run on ARM systems, but with a significant reduction in performance.

1. Install <a href="https://docs.docker.com/docker-for-windows/install/">Docker for Windows</a>.

{{site.data.alerts.callout_success}}
Docker for Windows requires 64bit Windows 10 Pro and Microsoft Hyper-V. Please see the <a href="https://docs.docker.com/docker-for-windows/install/#what-to-know-before-you-install">official documentation</a> for more details. Note that if your system does not satisfy the stated requirements, you can try using <a href="https://docs.docker.com/toolbox/overview/">Docker Toolbox</a>.
{{site.data.alerts.end}}

1. In PowerShell, confirm that the Docker daemon is running in the background:

{% include_cached copy-clipboard.html %}
~~~ powershell
docker version
~~~

If you see an error, start Docker for Windows.

1. <a href="https://docs.docker.com/docker-for-windows/#/shared-drives">Share your local drives</a>. This makes it possible to mount local directories as data volumes to persist node data after containers are stopped or deleted.

1. In PowerShell, pull the image for the {{page.release_info.version}} release of CockroachDB from <a href="https://hub.docker.com/r/{{page.release_info.docker_image}}/" class="win-docker-step3" id="win-docker-step3-{{page.version.version}}" data-eventcategory="win-docker-step3">Docker Hub</a>:

{% include_cached copy-clipboard.html %}
~~~ powershell
docker pull {{page.release_info.docker_image}}:{{page.release_info.version}}
~~~

1. Keep up-to-date with CockroachDB releases and best practices:

{% include marketo-install.html uid="2" %}

</section>
</div>

<h2 id="whats-next">What&#39;s next?</h2>

Expand Down
Loading