Applies the Vale findings spike review's `ensure`, `should`, and `since` decisions, following `word-choice.md#choose-words-that-have-one-meaning`. ## `ensure`, `ensures`, `ensuring`: every row marked valid - 148 lines in 70 files. - Most became `make sure`, `makes sure`, or `making sure`. - When the subject isn't a person, I used a verb that reads better, such as `guarantees`, `keeps`, `prevents`, `maintains`, or `provides`. - `admin/monitoring/health-check.md:227`: "Make sure that" is now "Make sure", so the step stays within `Coder.StepLength`. - Left as-is: `admin/setup/configuration-reference.md:1339`, which is generated from `codersdk`. ## `should` and `since`: only rows with a verdict or a note - `.style/README.md`: "what should be routed elsewhere" is now "what to route elsewhere". - `.style/content-guidelines.md`: - "Avoid mixing those modes within a single page." - "Every page must be accurate" - "Check docs claims against the actual implementation" - "must include the documentation" - "Support owns the content they produce." - "because they don't change" - `.style/styles/Coder/README.md`: "must link to the matching section". - `admin/external-auth.md`: - "The redirect URI for Gitea is ..." - "Use custom authentication and token URLs ...", which is now active voice. - `envbuilder-releases-known-issues.md`: "so it's experimental and prone to breaking changes". Rows marked unsure with no note were left alone: `content-guidelines.md` lines 49, 330, and 405, and `envbuilder/index.md:24`. The changed files have no new findings from other rules. --- AI-generated by Superblink on behalf of @nickvigilante. --------- Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
149 lines
5.8 KiB
Markdown
149 lines
5.8 KiB
Markdown
---
|
|
title: Install Coder via Docker
|
|
---
|
|
|
|
You can install and run Coder using the official Docker images published on [GitHub Container Registry](https://github.com/coder/coder/pkgs/container/coder).
|
|
|
|
## Requirements
|
|
|
|
- Docker.
|
|
See the [official installation documentation](https://docs.docker.com/install/).
|
|
|
|
- A Linux host.
|
|
|
|
- 2 CPU cores and 4 GB memory free on your machine.
|
|
|
|
> [!IMPORTANT]
|
|
> This guide is for **Linux** hosts only.
|
|
> The `getent` and `--group-add` Docker socket patterns used below are Linux-specific and do not translate cleanly to macOS Docker runtimes.
|
|
> For macOS, install Coder using the [standalone binary](https://coder.com/downloads) instead.
|
|
|
|
<div class="tabs">
|
|
|
|
## Install Coder via `docker compose`
|
|
|
|
Coder publishes a [docker compose example](../../../compose.yaml) which includes a PostgreSQL container and volume.
|
|
|
|
1. Make sure you have [Docker Compose](https://docs.docker.com/compose/install/) installed.
|
|
|
|
1. Download the [`docker-compose.yaml`](../../../compose.yaml) file.
|
|
|
|
1. Update `group_add:` in `docker-compose.yaml` with the `gid` of `docker` group.
|
|
|
|
You can get the `docker` group `gid` by running the below command:
|
|
|
|
```sh
|
|
getent group docker | cut -d: -f3
|
|
```
|
|
|
|
1. Start Coder with `docker compose up`
|
|
|
|
1. Visit the web UI via the configured url.
|
|
|
|
1. 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](../../admin/setup/index.md).
|
|
|
|
## 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.
|
|
|
|
```sh
|
|
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.
|
|
|
|
```sh
|
|
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
|
|
```
|
|
|
|
</div>
|
|
|
|
## 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](https://github.com/coder/coder/pkgs/container/coder-preview) 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](#install-coder-via-docker-run) with `ghcr.io/coder/coder-preview:latest`.
|
|
|
|
## Troubleshooting
|
|
|
|
### Cannot connect to the Docker daemon
|
|
|
|
If you see an error like:
|
|
|
|
```txt
|
|
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](../../get-started/index.md#cannot-connect-to-the-docker-daemon) for platform-specific steps.
|
|
|
|
If Docker is installed and running but Coder still cannot connect, the daemon might 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:
|
|
|
|
```sh
|
|
# 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..."
|
|
|
|
Make sure you have an externally-reachable `CODER_ACCESS_URL` set.
|
|
See [troubleshooting templates](../../templates/troubleshooting.md) 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](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)
|
|
|
|
### I cannot add Docker templates
|
|
|
|
Coder runs as a non-root user, we use `--group-add` to make sure 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 might 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](../../admin/setup/index.md#tunnel).
|
|
For production deployments, we recommend setting an [access URL](../../admin/setup/index.md#access-url)
|
|
|
|
## Next steps
|
|
|
|
- [Create your first template](../../templates/template-from-scratch.md)
|
|
- [Control plane configuration](../../admin/setup/index.md)
|