2022-09-08 19:41:00 +00:00
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
Docker is required. See the [official installation documentation ](https://docs.docker.com/install/ ).
## Run Coder with built-in database and tunnel (quick)
For proof-of-concept deployments, you can run a complete Coder instance with
2022-09-21 22:38:51 +00:00
the following command:
2022-09-08 19:41:00 +00:00
```sh
export CODER_DATA=$HOME/.config/coderv2-docker
2022-09-28 13:33:36 +00:00
export DOCKER_GROUP=$(getent group docker | cut -d: -f3)
2022-09-08 19:41:00 +00:00
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 \
2022-09-28 13:33:36 +00:00
--group-add $DOCKER_GROUP \
2022-09-08 19:41:00 +00:00
ghcr.io/coder/coder:latest
```
2022-09-28 13:33:36 +00:00
**< sup > Note:</ sup > ** < sup > 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.</ sup >
2022-09-08 19:41:00 +00:00
Coder configuration is defined via environment variables.
Learn more about Coder's [configuration options ](../admin/configure.md ).
## Run Coder with access URL and external PostgreSQL (recommended)
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.
```sh
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 \
ghcr.io/coder/coder:latest
```
Coder configuration is defined via environment variables.
Learn more about Coder's [configuration options ](../admin/configure.md ).
## Run Coder with docker-compose
2022-09-09 16:04:02 +00:00
Coder's publishes a [docker-compose example ](https://github.com/coder/coder/blob/main/docker-compose.yaml ) which includes
2022-09-08 19:41:00 +00:00
an PostgreSQL container and volume.
1. Install [Docker Compose ](https://docs.docker.com/compose/install/ )
2. Clone the `coder` repository:
```console
git clone https://github.com/coder/coder.git
```
3. Start Coder with `docker-compose up` :
2022-09-13 14:53:41 +00:00
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.
2022-09-28 13:33:36 +00:00
2022-09-13 14:53:41 +00:00
For proof-of-concept deployments, you can use [Coder's tunnel ](../admin/configure.md#tunnel ):
2022-09-08 19:41:00 +00:00
2022-09-13 14:53:41 +00:00
```sh
cd coder
CODER_TUNNEL=true docker-compose up
```
For production deployments, we recommend setting an [access URL ](../admin/configure.md#access-url ):
```sh
2022-09-08 19:41:00 +00:00
cd coder
2022-09-13 14:53:41 +00:00
CODER_ACCESS_URL=https://coder.example.com docker-compose up
2022-09-08 19:41:00 +00:00
```
2022-09-13 14:53:41 +00:00
> Without `CODER_ACCESS_URL` or `CODER_TUNNEL` set, Coder will bind to `localhost:7080`. This will only work for Docker-based templates.
2022-09-08 19:41:00 +00:00
2022-09-28 13:33:36 +00:00
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.
2022-09-13 05:17:01 +00:00
5. Follow the on-screen instructions log in and create your first template and workspace
2022-09-08 19:41:00 +00:00
## Troubleshooting
### Docker-based workspace is stuck in "Connecting..."
Ensure you have an externally-reachable `CODER_ACCESS_URL` set. See [troubleshooting templates ](../templates.md#creating-and-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 ](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user )
## Next steps
- [Quickstart ](../quickstart.md )
- [Configuring Coder ](../admin/configure.md )
- [Templates ](../templates.md )