2026-09-08 12:34:00 -04:00
---
title : Install Coder via Docker
---
2024-10-05 08:52:04 -07:00
2023-08-23 12:27:57 +03:00
You can install and run Coder using the official Docker images published on
[GitHub Container Registry ](https://github.com/coder/coder/pkgs/container/coder ).
2022-09-08 15:41:00 -04:00
## Requirements
2024-10-05 08:52:04 -07:00
- Docker. See the
[official installation documentation ](https://docs.docker.com/install/ ).
2022-09-08 15:41:00 -04:00
2026-05-28 10:48:53 -04:00
- A Linux host.
2023-03-26 08:39:20 -04:00
2024-10-05 08:52:04 -07:00
- 2 CPU cores and 4 GB memory free on your machine.
2024-02-16 15:53:03 +03:00
2026-05-28 10:48:53 -04:00
> [!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.
2025-12-03 17:02:08 +05:00
<div class="tabs">
## Install Coder via `docker compose`
Coder publishes a
2026-06-22 11:39:12 -04:00
[docker compose example ](../../compose.yaml )
2025-12-03 17:02:08 +05:00
which includes a PostgreSQL container and volume.
1. Make sure you have [Docker Compose ](https://docs.docker.com/compose/install/ )
installed.
1. Download the
2026-06-22 11:39:12 -04:00
[`docker-compose.yaml` ](../../compose.yaml )
2025-12-03 17:02:08 +05:00
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:
2026-07-15 14:07:09 -04:00
```sh
2025-12-03 17:02:08 +05:00
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).
2024-10-05 08:52:04 -07:00
## Install Coder via ` docker run`
2024-02-16 15:53:03 +03:00
2024-10-05 08:52:04 -07:00
### Built-in database (quick)
2022-09-08 15:41:00 -04:00
2023-08-23 12:27:57 +03:00
For proof-of-concept deployments, you can run a complete Coder instance with the
following command.
2022-09-08 15:41:00 -04:00
2026-07-15 14:07:09 -04:00
` ``sh
2022-09-08 15:41:00 -04:00
export CODER_DATA=$HOME/.config/coderv2-docker
2022-09-28 16:33:36 +03:00
export DOCKER_GROUP=$(getent group docker | cut -d: -f3)
2022-09-08 15:41:00 -04:00
mkdir -p $CODER_DATA
docker run --rm -it \
-v $CODER_DATA:/home/coder/.config \
-v /var/run/docker.sock:/var/run/docker.sock \
2022-09-28 16:33:36 +03:00
--group-add $DOCKER_GROUP \
2022-09-08 15:41:00 -04:00
ghcr.io/coder/coder:latest
` ``
2024-10-05 08:52:04 -07:00
### External database (recommended)
2022-09-08 15:41:00 -04:00
2022-10-17 19:24:49 -05:00
For production deployments, we recommend using an external PostgreSQL database
2024-02-16 15:53:03 +03:00
(version 13 or higher). Set ` CODER_ACCESS_URL` to the external URL that users
and workspaces will use to connect to Coder.
2022-09-08 15:41:00 -04:00
2026-07-15 14:07:09 -04:00
` ``sh
2024-02-16 15:53:03 +03:00
export DOCKER_GROUP=$(getent group docker | cut -d: -f3)
2022-09-08 15:41:00 -04:00
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 \
2024-02-16 15:53:03 +03:00
--group-add $DOCKER_GROUP \
2022-09-08 15:41:00 -04:00
ghcr.io/coder/coder:latest
` ``
2025-12-03 17:02:08 +05:00
</div>
2024-02-16 15:53:03 +03:00
2025-02-17 07:36:14 -05:00
## Install the preview release
2025-03-10 15:58:20 -05:00
> [!TIP]
> We do not recommend using preview releases in production environments.
2025-02-17 07:36:14 -05:00
2025-02-17 12:36:06 -05:00
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`.
2025-02-17 07:36:14 -05:00
2022-09-08 15:41:00 -04:00
## Troubleshooting
2026-05-05 12:44:39 -05:00
### Cannot connect to the Docker daemon
If you see an error like:
2026-07-15 14:07:09 -04:00
` ``txt
2026-05-05 12:44:39 -05:00
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
2026-06-29 16:07:10 -04:00
[Troubleshooting section of the get started guide](../get-started/index.md#cannot-connect-to-the-docker-daemon)
2026-05-05 12:44:39 -05:00
for platform-specific steps.
2026-07-08 11:33:02 -04:00
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:
` ``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 Coder server.
2022-09-08 15:41:00 -04:00
### Docker-based workspace is stuck in "Connecting..."
2023-08-23 12:27:57 +03:00
Ensure you have an externally-reachable ` CODER_ACCESS_URL` set. See
2024-10-05 08:52:04 -07:00
[troubleshooting templates](../admin/templates/troubleshooting.md) for more
steps.
2022-09-08 15:41:00 -04:00
### Permission denied while trying to connect to the Docker daemon socket
2023-08-23 12:27:57 +03:00
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)
2022-09-08 15:41:00 -04:00
2024-10-05 08:52:04 -07:00
### 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
2026-04-23 10:31:55 +05:00
` /var/run/docker.sock` is not group writable or does not belong to the ` docker`
2024-10-05 08:52:04 -07:00
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 )
2022-09-08 15:41:00 -04:00
## Next steps
2024-10-05 08:52:04 -07:00
- [Create your first template ](../tutorials/template-from-scratch.md )
2026-09-08 12:34:00 -04:00
- [Control plane configuration ](../admin/setup/index.md )