4.5 KiB
Running headscale in a container
!!! 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**.
Last update : 01/05/2023 - Headscale 0.22.1
Goal
This documentation has the goal of showing a user how-to set up and run headscale in a Docker container.
The Docker image can be found on Docker Hub here.
Configure and run headscale
1. Prepare a directory on the host Docker node in your directory of choice, used to hold headscale files.
mkdir -p ./headscale/config && cd ./headscale/config
!!! info "Database"
This tutorial uses SQLite for simplicity reasons, in a large environnement, it's recommended to use Postgres,
please refer the configuration file
2. Create an empty SQLite datebase in the headscale directory:
touch ./config/db.sqlite
3. Create an ACL file in the headscale directory:
touch ./config/ACL.json
Edit the file and put a base ACL in it :
{
"acls": [
{ "action": "accept", "src": ["*:*"], "dst": ["*:*"] }
]
}
4. Download a copy of the example configuration from the headscale repository and place it at ./config/config.yaml
wget -O ./config/config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml || curl https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml -o ./config/config.yaml
Modify the config file to your preferences before launching Docker container. Here are some settings that you likely want to change:
Change Headscale's server url to your hostname or host IP
server_url: http://your-host-name:8080
Listen to 0.0.0.0 so the services are accessible outside the container
listen_addr: 0.0.0.0:8080 #For Headscale
metrics_listen_addr: 0.0.0.0:9090 #For the metrics
Bind the ACL file we created above:
acl_policy_path: "/etc/headscale/ACL.json"
!!! warning "/var/lib isn't an editable path in the container"
Because /var/lib isn't an editable path in the container, we will need to replace
in the config file all those /var/lib paths to /etc.
Example :
```yaml
# The default /var/lib path is not writable in the container
private_key_path: /etc/headscale/private.key
```
5. Start the headscale server while working in the host headscale directory:
Replace with the current version, and your good to go !
docker run \
--name headscale \
--detach \
--restart unless-stopped \
--volume $(pwd)/config:/etc/headscale/ \
--publish 127.0.0.1:8080:8080 \
--publish 127.0.0.1:9090:9090 \
headscale/headscale:<VERSION> \
headscale serve
!!! note "About the docker run command"
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/` (outside the container) under `/etc/headscale` (inside the container),
forward port 8080 out of the container so the `headscale` instance becomes available and then detach so
headscale runs in the background.
The restart flag will made the instance restart unless if you stopped it manually
6. 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:9090/metrics
7. Launch command in the container :
docker exec headscale <COMMAND>
!!! note "Debugging & using a shell with Headscale"
The `headscale/headscale` Docker container 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:0.22.1-debug`.
To run the debug Docker container, use the exact same run command as above, but replace
`headscale/headscale:<VERSION>` with `headscale/headscale:<VERSION>-debug`. The two
containers are compatible with each other, so you can alternate between them.
To launch a shell in the container, use:
```
docker run -it headscale sh
```