2022-01-02 11:11:36 -07:00
# Running headscale in a container
2023-03-27 11:50:41 -06:00
!!! warning "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** .
2022-01-02 11:11:36 -07:00
## Goal
This documentation has the goal of showing a user how-to set up and run `headscale` in a container.
2022-01-02 12:48:57 -07:00
[Docker ](https://www.docker.com ) is used as the reference container implementation, but there is no reason that it should
2022-01-05 23:10:28 -07:00
not work with alternatives like [Podman ](https://podman.io ). The Docker image can be found on Docker Hub [here ](https://hub.docker.com/r/headscale/headscale ).
2022-01-02 11:11:36 -07:00
## Configure and run `headscale`
2022-01-05 23:10:28 -07:00
1. Prepare a directory on the host Docker node in your directory of choice, used to hold `headscale` configuration and the [SQLite ](https://www.sqlite.org/ ) database:
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
```shell
mkdir -p ./headscale/config
cd ./headscale
```
1. ** (Strongly Recommended)** Download a copy of the [example configuration ](https://github.com/juanfont/headscale/blob/main/config-example.yaml ) from the headscale repository.
- Using `wget` :
```shell
wget -O ./config/config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml
```
- Using `curl` :
```shell
curl https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml -o ./config/config.yaml
```
2024-08-30 08:59:24 -06:00
Modify the config file to your preferences before launching Docker container.
2024-03-22 12:55:20 -06:00
2024-08-30 08:59:24 -06:00
Alternatively, you can mount `/var/lib` and `/var/run` from your host system by adding
`--volume $(pwd)/lib:/var/lib/headscale` and `--volume $(pwd)/run:/var/run/headscale`
in the next step.
2024-03-22 12:55:20 -06:00
1. Start the headscale server while working in the host headscale directory:
```shell
docker run \
--name headscale \
--detach \
--volume $(pwd)/config:/etc/headscale/ \
--publish 127.0.0.1:8080:8080 \
--publish 127.0.0.1:9090:9090 \
headscale/headscale:< VERSION > \
2024-09-03 05:04:20 -06:00
serve
2024-03-22 12:55:20 -06:00
```
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 will mount `config/` under `/etc/headscale` , forward port 8080 out of the container so the
`headscale` instance becomes available and then detach so headscale runs in the background.
Example `docker-compose.yaml`
```yaml
version: "3.7"
2024-08-30 08:59:24 -06:00
2024-03-22 12:55:20 -06:00
services:
headscale:
2024-09-03 05:04:20 -06:00
image: headscale/headscale:< VERSION >
2024-03-22 12:55:20 -06:00
restart: unless-stopped
container_name: headscale
ports:
- "127.0.0.1:8080:8080"
- "127.0.0.1:9090:9090"
volumes:
2024-09-03 05:04:20 -06:00
# Please change < CONFIG_PATH > to the fullpath of the config folder just created
- < CONFIG_PATH > :/etc/headscale
command: serve
2024-03-22 12:55:20 -06:00
```
1. Verify `headscale` is running:
Follow the container logs:
```shell
docker logs --follow headscale
```
Verify running containers:
```shell
docker ps
```
Verify `headscale` is available:
```shell
curl http://127.0.0.1:9090/metrics
```
1. Create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)):
```shell
docker exec headscale \
2024-09-03 05:04:20 -06:00
headscale users create myfirstuser
2024-03-22 12:55:20 -06:00
```
2022-01-02 11:11:36 -07:00
### Register a machine (normal login)
On a client machine, execute the `tailscale` login command:
```shell
tailscale up --login-server YOUR_HEADSCALE_URL
```
To register a machine when running `headscale` in a container, take the headscale command and pass it to the container:
```shell
2022-03-22 06:45:30 -06:00
docker exec headscale \
2024-09-04 06:38:38 -06:00
headscale nodes register --user myfirstuser --key < YOUR_MACHINE_KEY >
2022-01-02 11:11:36 -07:00
```
### Register machine using a pre authenticated key
Generate a key using the command line:
```shell
2022-03-22 06:45:30 -06:00
docker exec headscale \
2024-09-04 06:38:38 -06:00
headscale preauthkeys create --user myfirstuser --reusable --expiration 24h
2022-01-02 11:11:36 -07:00
```
This will return a pre-authenticated key that can be used to connect a node to `headscale` during the `tailscale` command:
```shell
tailscale up --login-server < YOUR_HEADSCALE_URL > --authkey < YOUR_AUTH_KEY >
```
## Debugging headscale running in Docker
The `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 `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 `headscale/headscale:x.x.x` with `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
2024-09-03 05:04:20 -06:00
The default command in the debug container is to run `headscale` , which is located at `/ko-app/headscale` inside the container.
2022-01-02 11:11:36 -07:00
Additionally, the debug container includes a minimalist Busybox shell.
To launch a shell in the container, use:
```
docker run -it headscale/headscale:x.x.x-debug sh
```
2024-09-03 05:04:20 -06:00
You can also execute commands directly, such as `ls /ko-app` in this example:
2022-01-02 11:11:36 -07:00
```
2024-09-03 05:04:20 -06:00
docker run headscale/headscale:x.x.x-debug ls /ko-app
2022-01-02 11:11:36 -07:00
```
Using `docker exec` allows you to run commands in an existing container.