mirror of
https://github.com/coder/coder.git
synced 2026-06-02 20:48:20 +00:00
Nick Vigilante
ea280c5a90
Closes DOCS-68. Promotes the existing "Linux only" guidance on `docs/install/docker.md` from an easy-to-miss bullet point to a prominent `[!IMPORTANT]` callout, and briefly states *why* the page is Linux-only so macOS readers do not waste time on the `getent` / `--group-add` snippets. ## Why this re-scope vs. the original ticket The original DOCS-68 scope was "add a macOS `getent` alternative". On inspection, that framing has three problems: 1. The Requirements section already says "A Linux machine. For macOS devices, start Coder using the standalone binary," so macOS users are already redirected. The signal just lives in a bullet that is easy to overlook. 2. The `--group-add $DOCKER_GROUP` mechanism that drives the `getent` call is Linux-specific. macOS Docker runtimes (Docker Desktop, Colima, Rancher Desktop, Podman) use a VM and forward the socket differently; the flag does not translate cleanly to any of them. 3. Defining a canonical macOS Docker path is the scope of [DEVREL-22](https://linear.app/codercom/issue/DEVREL-22) (recommend Colima / Rancher / Podman alternatives in the Quick Start guide). DOCS-68 should not pre-empt that work. This PR narrows the fix to making the existing macOS guidance unmissable. A real macOS Docker install path can come as a separate follow-up once DEVREL-22 lands and the recommended runtime is settled. <details> <summary>Decision log</summary> * **(A) Close DOCS-68 as absorbed by DEVREL-22.** Rejected — the install page still has a discoverability problem that DEVREL-22 (Quick Start) will not fix. * **(B) Re-scope DOCS-68 to a narrow today-fix (this PR).** Selected. * **(C) Defer DOCS-68 until DEVREL-22 lands.** Rejected — the install page is shipping the weaker guidance every day until then. </details> > [!NOTE] > This is a docs-only change. No product code was modified. --- *Generated by Coder Agents on behalf of @nickvigilante.*
147 lines
4.9 KiB
Markdown
147 lines
4.9 KiB
Markdown
# 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](./cli.md) instead.
|
|
|
|
<div class="tabs">
|
|
|
|
## Install Coder via `docker compose`
|
|
|
|
Coder publishes a
|
|
[docker compose example](https://github.com/coder/coder/blob/main/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`](https://github.com/coder/coder/blob/main/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:
|
|
|
|
```shell
|
|
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.
|
|
|
|
```shell
|
|
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.
|
|
|
|
```shell
|
|
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:
|
|
|
|
```text
|
|
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
|
|
[quickstart troubleshooting](../tutorials/quickstart.md#cannot-connect-to-the-docker-daemon)
|
|
for platform-specific steps.
|
|
|
|
### Docker-based workspace is stuck in "Connecting..."
|
|
|
|
Ensure you have an externally-reachable `CODER_ACCESS_URL` set. See
|
|
[troubleshooting templates](../admin/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 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 (e.g. 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](../tutorials/template-from-scratch.md)
|
|
- [Control plane configuration](../admin/setup/index.md#configure-control-plane-access)
|