New
Boost Developer Productivity & Streamline Onboarding with CDE's

Download the Whitepaper

Docker

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

See an opportunity to improve our docs? Make an edit.