coder/docs/install/docker.md

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 machine. For macOS devices, start Coder using the standalone binary.

• 2 CPU cores and 4 GB memory free on your machine.

Install Coder via docker compose

Coder publishes a docker compose example which includes a PostgreSQL container and volume.

1. Make sure you have Docker Compose installed.

2. Download the docker-compose.yaml file.

3. 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:

   getent group docker | cut -d: -f3
   

4. Start Coder with docker compose up

5. Visit the web UI via the configured url.

6. 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 quickstart troubleshooting for platform-specific steps.

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 (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. For production deployments, we recommend setting an access URL

Next steps

• Create your first template
• Control plane configuration