# Install Coder via Docker

You can install and run Coder using the official Docker images published on
[GitHub Container Registry](https://github.com/coder/coder/pkgs/container/coder).

## Requirements [#requirements]

* Docker. See the
  [official installation documentation](https://docs.docker.com/install/).

* A Linux host.

* 2 CPU cores and 4 GB memory free on your machine.

<Callout type="idea" title="Important">
  This guide is for **Linux** hosts only. The `getent` and `--group-add`
  Docker socket patterns used below are Linux-specific and do not translate
  cleanly to macOS Docker runtimes. For macOS, install Coder using the
  [standalone binary](/beta-docs/install/cli/) instead.
</Callout>

<Tabs items="[&#x22;Install Coder via docker compose&#x22;, &#x22;Install Coder via docker run&#x22;]" groupId="coder-docs-tab:install-coder-via-docker-compose-install-coder-via-docker-run" persist="true">
  <Tab value="Install Coder via docker compose">
    Coder publishes a
    [docker compose example](https://github.com/coder/coder/blob/release/2.37/compose.yaml)
    which includes a PostgreSQL container and volume.

    1. Make sure you have [Docker Compose](https://docs.docker.com/compose/install/)
       installed.

    2. Download the
       [`docker-compose.yaml`](https://github.com/coder/coder/blob/release/2.37/compose.yaml)
       file.

    3. Update `group_add:` in `docker-compose.yaml` with the `gid` of `docker`
       group. You can get the `docker` group `gid` by running the below command:

       ```sh
       getent group docker | cut -d: -f3
       ```

    4. Start Coder with `docker compose up`

    5. Visit the web UI via the configured url.

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

    Coder configuration is defined via environment variables. Learn more about
    Coder's [configuration options](/beta-docs/admin/setup/).
  </Tab>

  <Tab value="Install Coder via docker run">
    ### Built-in database (quick) [#built-in-database-quick]

    For proof-of-concept deployments, you can run a complete Coder instance with the
    following command.

    ```sh
    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
    ```

    ### External database (recommended) [#external-database-recommended]

    For production deployments, we recommend using an external PostgreSQL database
    (version 13 or higher). Set `CODER_ACCESS_URL` to the external URL that users
    and workspaces will use to connect to Coder.

    ```sh
    export DOCKER_GROUP=$(getent group docker | cut -d: -f3)
    docker run --rm -it \
      -e CODER_ACCESS_URL="https://coder.example.com" \
      -e CODER_PG_CONNECTION_URL="postgresql://username:password@database/coder" \
      -v /var/run/docker.sock:/var/run/docker.sock \
      --group-add $DOCKER_GROUP \
      ghcr.io/coder/coder:latest
    ```
  </Tab>
</Tabs>

## Install the preview release [#install-the-preview-release]

<Callout type="success" title="Tip">
  We do not recommend using preview releases in production environments.
</Callout>

You can install and test a
[preview release of Coder](https://github.com/coder/coder/pkgs/container/coder-preview)
by using the `coder-preview:latest` image tag.
This image is automatically updated with the latest changes from the `main` branch.

Replace `ghcr.io/coder/coder:latest` in the `docker run` command in the
[steps above](#install-coder-via-docker-run) with `ghcr.io/coder/coder-preview:latest`.

## Troubleshooting [#troubleshooting]

### Cannot connect to the Docker daemon [#cannot-connect-to-the-docker-daemon]

If you see an error like:

```txt
Error: Error pinging Docker server: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
```

Docker is not installed or not running on the host. Install Docker and start the
daemon before creating a workspace from a Docker-based template. Refer to the
[Troubleshooting section of the get started guide](/beta-docs/get-started/#cannot-connect-to-the-docker-daemon)
for platform-specific steps.

If Docker is installed and running but Coder still cannot connect, the daemon may expose its socket at a path other than `/var/run/docker.sock`.
This can happen on any operating system when Docker runs through a tool that uses a per-user socket, such as rootless Docker on Linux, or Colima, Podman, or Rancher Desktop on macOS.
Point Coder at the right socket with `DOCKER_HOST`.

Find the socket path first.
For example, run `colima status` for Colima, or `docker context inspect` to read the endpoint of the active Docker context.
Default socket paths vary by tool, so consult your tool's documentation and treat the following as examples only:

```sh
# rootless Docker (Linux)
export DOCKER_HOST="unix://${XDG_RUNTIME_DIR}/docker.sock"

# Colima (macOS)
export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"
```

To persist the setting, add the `export` line to your shell's startup file, such as `~/.bashrc`, `~/.zshrc`, or `~/.config/fish/config.fish`.
Then restart the Coder server.

### Docker-based workspace is stuck in "Connecting..." [#docker-based-workspace-is-stuck-in-connecting]

Ensure you have an externally-reachable `CODER_ACCESS_URL` set. See
[troubleshooting templates](/beta-docs/admin/templates/troubleshooting/) for more
steps.

### Permission denied while trying to connect to the Docker daemon socket [#permission-denied-while-trying-to-connect-to-the-docker-daemon-socket]

See Docker's official documentation to
[Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)

### I cannot add Docker templates [#i-cannot-add-docker-templates]

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

### I cannot add cloud-based templates [#i-cannot-add-cloud-based-templates]

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](/beta-docs/admin/setup/#tunnel). For production deployments, we
recommend setting an [access URL](/beta-docs/admin/setup/#access-url)

## Next steps [#next-steps]

* [Create your first template](/beta-docs/tutorials/template-from-scratch/)
* [Control plane configuration](/beta-docs/admin/setup/#configure-control-plane-access)