Adds `Coder.StepLength`, a Vale `script` rule for [Keep steps short](https://github.com/coder/coder/blob/main/docs/.style/style-guide/procedural-writing.md#keep-steps-short). It flags an ordered-list step whose instruction, the step's first paragraph, has more than 20 words, counted as [How to count words](https://github.com/coder/coder/blob/main/docs/.style/style-guide/voice-and-tone.md#how-to-count-words) describes. Paragraphs below the instruction explain the step and aren't counted. - Severity: `warning`. - Scope: `docs/**` except `docs/.style/style-guide/**`. - Baseline: 124 findings in 60 hand-written files. The cleanup shortens each long instruction, moves its explanation into one paragraph below it, or splits a step that holds several actions. After cleanup `vale docs/` reports 0 `Coder.StepLength` findings, and the other rules report no new findings on the changed files. - The guide section now says the limit covers the instruction, and that one action or one explanation must not be broken across paragraphs to meet it. - Generated pages (`docs/reference/{api,cli,agent-api}`, `configuration-reference.md`, `prometheus.md`): no findings, so no `.vale.ini` exclusion is needed. Linear: DOCS-1272 <details><summary>Decision log</summary> **Review change (Ian's review)** - The first version limited every paragraph of a step to 20 words. The cleanup for it chopped explanations into several short paragraphs, which made steps harder to read and sometimes changed their meaning. - The rule now counts only the first paragraph segment of each step. The content files were reset to `main` and the cleanup was redone against the narrower rule. - Cleanup preferences, in order: shorten the instruction; keep a short instruction and put the explanation, with its original wording, in one paragraph below it; split a step into one step for each action; for descriptive lists (such as "How it works"), keep each item one statement. - `docs/admin/users/oidc-auth/microsoft.md` keeps the split into separate steps, with Ian's wording suggestions applied. "click" became "select" in step 16 because `Coder.SelectClick` flags it. **Rule shape** - A `script` rule (Tengo) with `scope: raw`, because the count depends on Markdown structure that per-paragraph scopes hide. - A step is an ordered-list item with a `1.` or `1)` marker. A nested ordered item is its own step. Bullets, even under a step, are not steps. - The instruction ends at a blank line, a fence, a nested list, a table row, a blockquote, block-level HTML, or an explicit hard break (`<br>`, a trailing backslash, or two trailing spaces). - Fenced code blocks, HTML comments, tables, images, and nested bullets add no words. - CRLF: `\r` counts as whitespace, and offsets come from the raw text. **Counting approximations (also in the rule header)** - A code span and a `**bold**` or `__bold__` span are one word each. - Words split on whitespace, so a hyphenated compound and `30 seconds` are one word. - Link text counts word by word, destinations are skipped, images add no words, and `<https://...>` autolinks are one word. - A token with no letter or digit, such as the `>` in `**A** > **B**`, is not a word. - Tengo indexes strings by rune but measures them in bytes, so the script rewrites each non-ASCII rune to ASCII of the same byte length first. **Tests** (fixtures under `/tmp/sltest/`, not committed; run with the repo `.vale.ini`, LF and CRLF) - Flagged: a long instruction, a short action and a long result in one paragraph, a long nested ordered step. - Not flagged: a long paragraph below a short instruction, text after a `<br>` hard break, a long paragraph after a code block, a long nested bullet. - LF and CRLF output is identical. - Pre-commit hooks (`fmt/markdown`, `lint/markdown`, `lint/emdash`, `lint/style-claims`, `lint/typos`) pass. - Not run on Windows or macOS. The rule is plain text processing, and the CRLF cases simulate Windows line endings on Linux. </details> *Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on behalf of @nickvigilante.*
5.8 KiB
title
| title |
|---|
| Install Coder via Docker |
You can install and run Coder using the official Docker images published on GitHub Container Registry.
Requirements
-
Docker. See the official installation documentation.
-
A Linux host.
-
2 CPU cores and 4 GB memory free on your machine.
Important
This guide is for Linux hosts only. The
getentand--group-addDocker socket patterns used below are Linux-specific and do not translate cleanly to macOS Docker runtimes. For macOS, install Coder using the standalone binary instead.
Install Coder via docker compose
Coder publishes a docker compose example which includes a PostgreSQL container and volume.
-
Make sure you have Docker Compose installed.
-
Download the
docker-compose.yamlfile. -
Update
group_add:indocker-compose.yamlwith thegidofdockergroup.You can get the
dockergroupgidby running the below command:getent group docker | cut -d: -f3 -
Start Coder with
docker compose up -
Visit the web UI via the configured url.
-
Follow the on-screen instructions log in and create your first template and workspace
Coder configuration is defined via environment variables. Learn more about Coder's configuration options.
Install Coder via docker run
Built-in database (quick)
For proof-of-concept deployments, you can run a complete Coder instance with the following command.
export CODER_DATA=$HOME/.config/coderv2-docker
export DOCKER_GROUP=$(getent group docker | cut -d: -f3)
mkdir -p $CODER_DATA
docker run --rm -it \
-v $CODER_DATA:/home/coder/.config \
-v /var/run/docker.sock:/var/run/docker.sock \
--group-add $DOCKER_GROUP \
ghcr.io/coder/coder:latest
External database (recommended)
For production deployments, we recommend using an external PostgreSQL database (version 13 or higher).
Set CODER_ACCESS_URL to the external URL that users and workspaces will use to connect to Coder.
export DOCKER_GROUP=$(getent group docker | cut -d: -f3)
docker run --rm -it \
-e CODER_ACCESS_URL="https://coder.example.com" \
-e CODER_PG_CONNECTION_URL="postgresql://username:password@database/coder" \
-v /var/run/docker.sock:/var/run/docker.sock \
--group-add $DOCKER_GROUP \
ghcr.io/coder/coder:latest
Install the preview release
Tip
We do not recommend using preview releases in production environments.
You can install and test a preview release of Coder by using the coder-preview:latest image tag.
This image is automatically updated with the latest changes from the main branch.
Replace ghcr.io/coder/coder:latest in the docker run command in the steps above with ghcr.io/coder/coder-preview:latest.
Troubleshooting
Cannot connect to the Docker daemon
If you see an error like:
Error: Error pinging Docker server: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
Docker is not installed or not running on the host. Install Docker and start the daemon before creating a workspace from a Docker-based template. Refer to the Troubleshooting section of the get started guide for platform-specific steps.
If Docker is installed and running but Coder still cannot connect, the daemon may expose its socket at a path other than /var/run/docker.sock.
This can happen on any operating system when Docker runs through a tool that uses a per-user socket, such as rootless Docker on Linux, or Colima, Podman, or Rancher Desktop on macOS.
Point Coder at the right socket with DOCKER_HOST.
Find the socket path first.
For example, run colima status for Colima, or docker context inspect to read the endpoint of the active Docker context.
Default socket paths vary by tool, so consult your tool's documentation and treat the following as examples only:
# rootless Docker (Linux)
export DOCKER_HOST="unix://${XDG_RUNTIME_DIR}/docker.sock"
# Colima (macOS)
export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"
To persist the setting, add the export line to your shell's startup file, such as ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish.
Then restart the control plane.
Docker-based workspace is stuck in "Connecting..."
Ensure you have an externally-reachable CODER_ACCESS_URL set.
See troubleshooting templates for more steps.
Permission denied while trying to connect to the Docker daemon socket
See Docker's official documentation to Manage Docker as a non-root user
I cannot add Docker templates
Coder runs as a non-root user, we use --group-add to ensure Coder has permissions to manage Docker via docker.sock.
If the host systems /var/run/docker.sock is not group writable or does not belong to the docker group, the above may not work as-is.
I cannot add cloud-based templates
In order to use cloud-based templates (for example, Kubernetes, AWS), you must have an external URL that users and workspaces will use to connect to Coder. For proof-of-concept deployments, you can use Coder's tunnel. For production deployments, we recommend setting an access URL