Local deployment

Coder for Docker allows you to deploy Coder to any machine on which Docker runs quickly.

Prerequisites

Coder for Docker works with the following platforms:

macOS 10.10+ with Docker Desktop 20.10

Note: If your computer uses an Apple silicon processor, you will need to install Rosetta 2 to emulate the x86_64 instruction set. To install it, run the following command in a terminal window:
```
softwareupdate --install-rosetta
```
Ubuntu Linux 20.04 (Focal Fossa) with Docker Community Edition 20.10
Windows 11 with Docker Desktop 20.10.

Note: Coder for Docker requires Windows Subsystem for Linux at this time.

At this time, Coder publishes builds for the x86-64 architecture only and does not support Arm-based processors, such Apple silicon or Amazon Graviton instances.

Installing Coder for Docker

Launch Docker Desktop.
If you've previously installed Coder, run sudo rm -rf ~/.coder in the terminal. Note: This command erases your Coder database and settings, so only run this if you'd like a clean install.
In the terminal, run the following to download the resources you need, including the images, and set up your Coder deployment (if you're using the terminal in Docker Desktop, omit the slashes and run as a single-line command):
```
docker run --rm -it \
   -p 7080:7080 \
   -v /var/run/docker.sock:/var/run/docker.sock \
   -v ~/.coder:/var/run/coder \
   codercom/coder:1.35.0
```
Please check the changelog for the latest Coder v1 release to add to the docker run command.

When this process is complete, Coder will print the URL you can use to access your deployment, as well as the admin credentials you'll need to log in:
```
> Welcome to Coder! 👋
> Head to http://localhost:7080 to get started!

> 🙋 Username: admin
> 🔑 Password: 5h...7n
```
Make a note of these values, because you will need these in the subsequent step.
Launch a web browser and navigate to the URL provided by Coder (e.g., http://localhost:7080). Log in using the credentials Coder provided.
Create a workspace using one of the Packaged images by clicking on New workspace in the center of the UI.

At this point, you're ready to use your workspace. See our getting started guide for detailed instructions on getting your first workspace up and running.

Usage notes

When running, Docker Desktop displays both your Coder deployment and your workspace.

You can also view runtime information (i.e., API calls) in the console where you started your deployment:

Dev URLs

To use a dev URL, set an environment variable when issuing the docker run command to start your deployment (be sure to replace the placeholder URL):

DEVURL_HOST="*.mycompany.com"

For example:

docker run --rm -it -p 7080:7080 -v /var/run/docker.sock:/var/run/docker.sock -v ~/.coder:/var/run/coder -e DEVURL_HOST="*.mycompany.com" codercom/coder:1.33.3

Use an external PostgreSQL database

Coder for Docker comes with an embedded database, but you can opt for an external database instead.

Admin password

If you want to set (or reset) your admin password, use the -e SUPER_ADMIN_PASSWORD=<password> flag with the docker run command.

Scaling

Coder for Docker is limited by the resources of the machine on which it runs. We recommend using Kubernetes or AWS EC2 providers if you would like automatic multi-machine scaling.

For organizations, we recommend one Docker host per team of 5-10 developers.

Docker Compose

You can also use Docker Compose to run Coder in Docker.

To do so:

Create a new directory (we recommend something like c4d, but you can name it whatever you'd like)
Within the newly created directory, create a file named docker-compose.yml that includes the following:

version: "3.5"
services:
  coder:
    image: docker.io/codercom/coder:1.33.3
    container_name: coderd
    restart: unless-stopped
    ports:
      - 7080:7080/tcp
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ${HOME}/.coder:/var/run/coder

By default, Coder will create a postgres database. If you'd like to use postgres in a separate container, use the example below:

version: "3.5"
services:
  coder:
    image: docker.io/codercom/coder:1.33.3
    container_name: coderd
    restart: unless-stopped
    ports:
      - 7080:7080/tcp
    networks:
      - coder
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ${HOME}/.coder:/var/run/coder
    environment:
      DB_EMBEDDED: ""
      DB_HOST: "db"
      DB_PORT: 5432
      DB_USER: postgres
      DB_PASSWORD: "password"
      DB_NAME: postgres
      DB_SSL_MODE: disable
  db:
    container_name: postgres
    image: postgres
    restart: unless-stopped
    ports:
      - 5432:5432/tcp
    networks:
      - coder
    environment:
      POSTGRES_PASSWORD: password
    volumes:
      - db-data:/var/lib/postgresql/data
networks:
  coder:
    name: coder_network
volumes:
  db-data: {}

In the terminal, navigate into the folder you created and run:

docker-compose up -d

Coder will now run in the background.

For more detailed information on the Docker Compose file, please see Docker's docs.

Coder templates

You can use templates with Coder for Docker to define how Coder builds your workspaces.

To use a standard Coder workspace template for Docker:

Change the workspace.type andworkspace.specs to docker
Remove any Kubernetes-specific workspace.specs.kubernetes values (e.g., cpu, memory, gpu)

Your configuration file will look something like the following:

version: 0.2
workspace:
  type: docker
  specs:
    docker:
      image:
        value: index.docker.io/codercom/enterprise-intellij:ubuntu
      container-based-vm:
        value: false
  configure:
    start:
    ...

Ensure that user IPs show up in the audit logs

If you would like users' IP addresses to show up in the audit logs (i.e., identify the originating client IP address, regardless of whether they're connecting through a proxy, load balancer, or other such service), use the following flags with the docker run command:

-e "PROXY_TRUSTED_HEADERS=X-Forwarded-For"
-e PROXY_TRUSTED_ORIGINS=172.17.0.0/16

Workspace providers

If you're interested in using Docker as a workspace provider, please see our deployment instructions.

Accessing the local PostgreSQL database

To query the local PostgreSQL database using the psql terminal-based front-end, follow these steps.

Run docker ps to get the name of the Coder container.
Exec into the Coder container and connect to the database.

docker exec -it <CODER_CONTAINER> psql --username=coder --host=0.0.0.0 --port=5433 --dbname=postgres

Known issues

Currently, Coder for Docker does not support:

The use of your own TLS certificates. If you'd like to use TLS with Coder for Docker, you'll need to run Coder behind a reverse proxy (e.g., Caddy or NGINX) and terminate TLS at that point. See our guide for information.
Air-gapped deployments/offline installs