Skip to content

# Running headscale in a container

Community documentation

This page is not actively maintained by the headscale authors and is written by community members. It is not verified by headscale developers.

It might be outdated and it might miss necessary steps.

A container runtime such as Docker or Podman is required. The container image can be found on Docker Hub and GitHub Container Registry. The container image URLs are:

- Docker Hub: `docker.io/headscale/headscale:<VERSION>`
- GitHub Container Registry: `ghcr.io/juanfont/headscale:<VERSION>`

## Configure and run headscale

1. Create a directory on the container host to store headscale's configuration and the SQLite database:

       mkdir -p ./headscale/{config,lib}
       cd ./headscale

2. Download the example configuration for your chosen version and save it as: `$(pwd)/config/config.yaml`. Adjust the configuration to suit your local environment. See Configuration for details.

3. Start headscale from within the previously created `./headscale` directory:

       docker run \
         --name headscale \
         --detach \
         --read-only \
         --tmpfs /var/run/headscale \
         --volume "$(pwd)/config:/etc/headscale:ro" \
         --volume "$(pwd)/lib:/var/lib/headscale" \
         --publish 127.0.0.1:8080:8080 \
         --publish 127.0.0.1:9090:9090 \
         --health-cmd "CMD headscale health" \
         docker.io/headscale/headscale:<VERSION> \
         serve

   Note: use `0.0.0.0:8080:8080` instead of `127.0.0.1:8080:8080` if you want to expose the container externally.

   This command mounts the local directories inside the container, forwards port 8080 and 9090 out of the container so the headscale instance becomes available and then detaches so headscale runs in the background.

   A similar configuration for `docker-compose`:

   docker-compose.yaml

       services:
         headscale:
           image: docker.io/headscale/headscale:<VERSION>
           restart: unless-stopped
           container_name: headscale
           read_only: true
           tmpfs:
             - /var/run/headscale
           ports:
             - "127.0.0.1:8080:8080"
             - "127.0.0.1:9090:9090"
           volumes:
             # Please set <HEADSCALE_PATH> to the absolute path
             # of the previously created headscale directory.
             - <HEADSCALE_PATH>/config:/etc/headscale:ro
             - <HEADSCALE_PATH>/lib:/var/lib/headscale
           command: serve
           healthcheck:
               test: ["CMD", "headscale", "health"]

4. Verify headscale is running:

   Follow the container logs:

       docker logs --follow headscale

   Verify running containers:

       docker ps

   Verify headscale is available:

       curl http://127.0.0.1:8080/health

Continue on the getting started page to register your first machine.

## Debugging headscale running in Docker

The Headscale container image is based on a distroless image that does not contain a shell or any other debug tools. If you need to debug headscale running in the Docker container, you can use the `-debug` variant, for example `docker.io/headscale/headscale:x.x.x-debug`.

### Running the debug Docker container

To run the debug Docker container, use the exact same commands as above, but replace `docker.io/headscale/headscale:x.x.x` with `docker.io/headscale/headscale:x.x.x-debug` (`x.x.x` is the version of headscale). The two containers are compatible with each other, so you can alternate between them.

### Executing commands in the debug container

The default command in the debug container is to run `headscale`, which is located at `/ko-app/headscale` inside the container.

Additionally, the debug container includes a minimalist Busybox shell.

To launch a shell in the container, use:

    docker run -it docker.io/headscale/headscale:x.x.x-debug sh

You can also execute commands directly, such as `ls /ko-app` in this example:

    docker run docker.io/headscale/headscale:x.x.x-debug ls /ko-app

Using `docker exec -it` allows you to run commands in an existing container.