Docker

Coder with Docker has the following advantages:

• Simple installation (everything is on a single box)
• Workspace images are easily configured
• Workspaces share resources for burst operations

Note that the below steps are only supported on a Linux distribution.

Requirements

• A Linux machine
• A running Docker daemon

Before you install If you would like your workspaces to be able to run Docker, we recommend that you install Sysbox before proceeding.

As part of the Sysbox installation you will be required to remove all existing Docker containers including containers used by Coder workspaces. Installing Sysbox ahead of time will reduce disruption to your Coder instance.

Instructions

1. Run Coder with Docker.

   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
   

   This will use Coder's tunnel and built-in database. See our Docker documentation for other configuration options such as running on localhost, using docker-compose, and external PostgreSQL.

2. In new terminal, install Coder in order to connect to your deployment through the CLI.

   curl -L https://coder.com/install.sh | sh
   

3. Run coder login <access url> and follow the interactive instructions to create your user.

4. Pull the "Docker" example template using the interactive coder templates init:

   coder templates init
   cd docker
   

5. Push up the template with coder templates push

6. Open the dashboard in your browser to create your first workspace:

   

   Then navigate to Templates > docker > Create Workspace

   

   Now wait a few moments for the workspace to build... After the first build, the image is cached and subsequent builds will take a few seconds.

7. Your workspace is ready to go!

   

   Open up a web application or SSH in.

8. If you want to modify the Docker image or template, edit the files in the previously created ./docker directory, then run coder templates push.

Using remote Docker host

You can use a remote Docker host in 2 ways.

1. Configuring docker provider to use a remote host over SSH or TCP.
2. Running an external provisoner on the remote docker host.

Troubleshooting

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.

Next Steps