Running headscale in a container¶
This page is not actively maintained by the headscale authors and is written by community members. It is not verified by
It might be outdated and it might miss necessary steps.
This documentation has the goal of showing a user how-to set up and run
headscale in a container. Docker is used as the reference container implementation, but there is no reason that it should not work with alternatives like Podman. The Docker image can be found on Docker Hub here.
Configure and run
- Prepare a directory on the host Docker node in your directory of choice, used to hold
headscaleconfiguration and the SQLite database:
- Create an empty SQlite datebase in the headscale directory:
- (Strongly Recommended) Download a copy of the [example configuration]config-example.yaml from the headscale repository.
(Advanced) If you would like to hand craft a config file instead of downloading the example config file, create a blank
headscale configuration in the headscale directory to edit:
Modify the config file to your preferences before launching Docker container. Here are some settings that you likely want:
# Change to your hostname or host IP server_url: http://your-host-name:8080 # Listen to 0.0.0.0 so it's accessible outside the container metrics_listen_addr: 0.0.0.0:9090 # The default /var/lib/headscale path is not writable in the container private_key_path: /etc/headscale/private.key # The default /var/lib/headscale path is not writable in the container noise: private_key_path: /etc/headscale/noise_private.key # The default /var/lib/headscale path is not writable in the container db_type: sqlite3 db_path: /etc/headscale/db.sqlite
- Start the headscale server while working in the host headscale directory:
0.0.0.0:8080:8080 instead of
127.0.0.1:8080:8080 if you want to expose the container externally.
This command will mount
/etc/headscale, forward port 8080 out of the container so the
headscale instance becomes available and then detach so headscale runs in the background.
Follow the container logs:
Verify running containers:
headscale is available:
- Create a user (tailnet):
Register a machine (normal login)¶
On a client machine, execute the
tailscale login command:
To register a machine when running
headscale in a container, take the headscale command and pass it to the container:
Register machine using a pre authenticated key¶
Generate a key using the command line:
This will return a pre-authenticated key that can be used to connect a node to
headscale during the
Debugging headscale running in Docker¶
headscale/headscale Docker container is based on a "distroless" image that does not contain a shell or any other debug tools. If you need to debug your application running in the Docker container, you can use the
-debug variant, for example
Running the debug Docker container¶
To run the debug Docker container, use the exact same commands as above, but replace
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
/bin/headscale inside the container.
Additionally, the debug container includes a minimalist Busybox shell.
To launch a shell in the container, use:
You can also execute commands directly, such as
ls /bin in this example:
docker exec allows you to run commands in an existing container.