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. If on macOS, please run Coder via the standalone binary.

Requirements

  • A Linux machine
  • A running Docker daemon

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 create

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

    login

    Then navigate to Templates > docker > Create Workspace

    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!

    ides

    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. Over SSH. See here for details.
  2. Over TCP. See here for details.

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.