Docker

You can install and run Coder using the official Docker images published on GitHub Container Registry.

Requirements

Docker is required. See the official installation documentation.

Run Coder with built-in database and tunnel (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 \
  -e CODER_TUNNEL=true \
  -v $CODER_DATA:/home/coder/.config \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --group-add $DOCKER_GROUP \
  ghcr.io/coder/coder:latest

Note: 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 writeable or does not belong to the docker group, the above may not work as-is.

Coder configuration is defined via environment variables. Learn more about Coder's configuration options.

For production deployments, we recommend using an external PostgreSQL database. Set ACCESS_URL to the external URL that users and workspaces will use to connect to Coder.

docker run --rm -it \
  -e CODER_ACCESS_URL="https://coder.example.com" \
  -e CODER_PG_CONNECTION_URL="postgresql://username:[email protected]/coder" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/coder/coder:latest

Coder configuration is defined via environment variables. Learn more about Coder's configuration options.

Run Coder with docker-compose

Coder's publishes a docker-compose example which includes an PostgreSQL container and volume.

  1. Install Docker Compose

  2. Clone the coder repository:

    git clone https://github.com/coder/coder.git
    
  3. Start Coder with docker-compose up:

    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:

    cd coder
    
    CODER_TUNNEL=true docker-compose up
    

    For production deployments, we recommend setting an access URL:

    cd coder
    
    CODER_ACCESS_URL=https://coder.example.com docker-compose up
    

    Without CODER_ACCESS_URL or CODER_TUNNEL set, Coder will bind to localhost:7080. This will only work for Docker-based templates.

  4. Visit the web ui via the configured url. You can add /login to the base url to create the first user via the ui.

  5. Follow the on-screen instructions log in and create your first template and workspace

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.