Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Running Headscale In A Container Documentation Updates. #1659

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Running Headscale In A Container Documentation Updates. #1659

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2ee8a51
doc: headscale will create a new sqlite file
canardleteer Dec 18, 2023
6a661c8
doc: clarify the example conf versioning
canardleteer Dec 18, 2023
64c766d
doc: note that private_key is missing in the example
canardleteer Dec 18, 2023
213fac7
doc: add derp private key remapping
canardleteer Dec 18, 2023
a766d25
doc: move the Advanced section of configuration
canardleteer Dec 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 11 additions & 12 deletions docs/running-headscale-container.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,9 @@ mkdir -p ./headscale/config
cd ./headscale
```

2. Create an empty SQlite datebase in the headscale directory:
2. **(Strongly Recommended)** Download a copy of the [example configuration](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository.

```shell
touch ./config/db.sqlite
```

3. **(Strongly Recommended)** Download a copy of the [example configuration](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository.
The following instructions are for running against `headscale/headscale:latest`, if you are using an older version, you will want to make sure you're getting the correct version of a default configuration file from the [tags](https://github.com/juanfont/headscale/tags) matching your version.
Comment on lines +25 to +27
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are admonition extension for such cases.

!!! warning "Strongly Recommended"
    
    Download a copy of the [example configuration](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While I make changes like these by re-basing on main, and adding those changes, I cannot validate the changes since make serve is not offered in the Makefile after a rebase on main (which is the validation step mentioned here). You can see those changes here in this branch if you'd like to take a look: https://github.com/canardleteer/headscale/blob/fix-docker-documentation-testing/docs/running-headscale-container.md

It does appear, than since my contribution, at least some of the changes proposed were added to the repository.

If those changes are fine as is, I can add them to this MR.


Using wget:

Expand All @@ -42,12 +38,6 @@ Using curl:
curl https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml -o ./config/config.yaml
```

**(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:

```shell
touch ./config/config.yaml
```

Modify the config file to your preferences before launching Docker container.
Here are some settings that you likely want:

Expand All @@ -57,15 +47,24 @@ 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
# NOTE: This is not present in the default configuration file.
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
derp:
private_key_path: /etc/headscale/derp_server_private.key
# The default /var/lib/headscale path is not writable in the container
db_type: sqlite3
db_path: /etc/headscale/db.sqlite
```

**(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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

!!! example "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:


```shell
touch ./config/config.yaml
```

4. Start the headscale server while working in the host headscale directory:

```shell
Expand Down