mirror of
https://github.com/juanfont/headscale.git
synced 2025-10-05 11:19:03 +02:00
162 lines
4.5 KiB
Markdown
162 lines
4.5 KiB
Markdown
# 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](https://www.docker.com) container.
|
|
|
|
The Docker image can be found on Docker Hub [here](https://hub.docker.com/r/headscale/headscale).
|
|
|
|
## Configure and run `headscale`
|
|
|
|
# 1. Prepare a directory on the host Docker node in your directory of choice, used to hold `headscale` files.
|
|
|
|
```shell
|
|
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](https://www.sqlite.org/) datebase in the headscale directory:
|
|
|
|
```shell
|
|
touch ./config/db.sqlite
|
|
```
|
|
|
|
# 3. Create an ACL file in the headscale directory:
|
|
|
|
```shell
|
|
touch ./config/ACL.json
|
|
```
|
|
|
|
Edit the file and put a base ACL in it :
|
|
|
|
```json
|
|
{
|
|
"acls": [
|
|
{ "action": "accept", "src": ["*:*"], "dst": ["*:*"] }
|
|
]
|
|
}
|
|
```
|
|
|
|
# 4. Download a copy of the [example configuration](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository and place it at ./config/config.yaml
|
|
|
|
```shell
|
|
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
|
|
|
|
```yaml
|
|
server_url: http://your-host-name:8080
|
|
```
|
|
|
|
Listen to 0.0.0.0 so the services are accessible outside the container
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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 <VERSION> with the current version, and your good to go !
|
|
|
|
```shell
|
|
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:
|
|
|
|
```shell
|
|
docker logs --follow headscale
|
|
```
|
|
|
|
Verify running containers:
|
|
|
|
```shell
|
|
docker ps
|
|
```
|
|
|
|
Verify `headscale` is available:
|
|
|
|
```shell
|
|
curl http://127.0.0.1:9090/metrics
|
|
```
|
|
|
|
# 7. Launch command in the container :
|
|
|
|
```shell
|
|
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
|
|
```
|