eyjhb/headscale
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Misc doc fixes (#2562)

Browse source 
* Link to stable and development docs in the README

* Add Tailscale SSH and autogroup:nonroot to features page

* Use @ when referencing users in policy

* Remove unmaintained headscale-webui

The project seems to be unmaintained (last commit: 2023-05-08) and it
only supports Headscale 0.22 or earlier.

* Use full image URL in container docs

This makes it easy to switch the container runtime from docker <->
podman.

* Remove version from docker-compose.yml example

This is now deprecated and yields a warning.
This commit is contained in:
nblock 2025-05-04 21:55:08 +02:00 • committed by GitHub
parent 45e38cb080
commit 9a86ffc102
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 32 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

8
README.md
View file

@ -7,8 +7,12 @@ An open source, self-hosted implementation of the Tailscale control server.
Join our [Discord server](https://discord.gg/c84AZQhmpx) for a chat. Join our [Discord server](https://discord.gg/c84AZQhmpx) for a chat.
**Note:** Always select the same GitHub tag as the released version you use **Note:** Always select the same GitHub tag as the released version you use
to ensure you have the correct example configuration and documentation. to ensure you have the correct example configuration. The `main` branch might
The `main` branch might contain unreleased changes. contain unreleased changes. The documentation is available for stable and
development versions:
* [Documentation for the stable version](https://headscale.net/stable/)
* [Documentation for the development version](https://headscale.net/development/)
## What is Tailscale ## What is Tailscale

4
docs/about/features.md
View file

@ -22,10 +22,12 @@ provides on overview of Headscale's feature and compatibility with the Tailscale
- [x] Embedded [DERP server](https://tailscale.com/kb/1232/derp-servers) - [x] Embedded [DERP server](https://tailscale.com/kb/1232/derp-servers)
- [x] Access control lists ([GitHub label "policy"](https://github.com/juanfont/headscale/labels/policy%20%F0%9F%93%9D)) - [x] Access control lists ([GitHub label "policy"](https://github.com/juanfont/headscale/labels/policy%20%F0%9F%93%9D))
- [x] ACL management via API - [x] ACL management via API
- [x] Some [Autogroups](https://tailscale.com/kb/1396/targets#autogroups), currently: `autogroup:internet` - [x] Some [Autogroups](https://tailscale.com/kb/1396/targets#autogroups), currently: `autogroup:internet`,
`autogroup:nonroot`
- [x] [Auto approvers](https://tailscale.com/kb/1337/acl-syntax#auto-approvers) for [subnet - [x] [Auto approvers](https://tailscale.com/kb/1337/acl-syntax#auto-approvers) for [subnet
routers](../ref/routes.md#automatically-approve-routes-of-a-subnet-router) and [exit routers](../ref/routes.md#automatically-approve-routes-of-a-subnet-router) and [exit
nodes](../ref/routes.md#automatically-approve-an-exit-node-with-auto-approvers) nodes](../ref/routes.md#automatically-approve-an-exit-node-with-auto-approvers)
- [x] [Tailscale SSH](https://tailscale.com/kb/1193/tailscale-ssh)
* [ ] Node registration using Single-Sign-On (OpenID Connect) ([GitHub label "OIDC"](https://github.com/juanfont/headscale/labels/OIDC)) * [ ] Node registration using Single-Sign-On (OpenID Connect) ([GitHub label "OIDC"](https://github.com/juanfont/headscale/labels/OIDC))
- [x] Basic registration - [x] Basic registration
- [x] Update user profile from identity provider - [x] Update user profile from identity provider

18
docs/ref/acls.md
View file

@ -64,10 +64,10 @@ Here are the ACL's to implement the same permissions as above:
// groups are collections of users having a common scope. A user can be in multiple groups // groups are collections of users having a common scope. A user can be in multiple groups
// groups cannot be composed of groups // groups cannot be composed of groups
"groups": { "groups": {
"group:boss": ["boss"], "group:boss": ["boss@"],
"group:dev": ["dev1", "dev2"], "group:dev": ["dev1@", "dev2@"],
"group:admin": ["admin1"], "group:admin": ["admin1@"],
"group:intern": ["intern1"] "group:intern": ["intern1@"]
}, },
// tagOwners in tailscale is an association between a TAG and the people allowed to set this TAG on a server. // tagOwners in tailscale is an association between a TAG and the people allowed to set this TAG on a server.
// This is documented [here](https://tailscale.com/kb/1068/acl-tags#defining-a-tag) // This is documented [here](https://tailscale.com/kb/1068/acl-tags#defining-a-tag)
@ -181,11 +181,11 @@ Here are the ACL's to implement the same permissions as above:
// We still have to allow internal users communications since nothing guarantees that each user have // We still have to allow internal users communications since nothing guarantees that each user have
// their own users. // their own users.
{ "action": "accept", "src": ["boss"], "dst": ["boss:*"] }, { "action": "accept", "src": ["boss@"], "dst": ["boss@:*"] },
{ "action": "accept", "src": ["dev1"], "dst": ["dev1:*"] }, { "action": "accept", "src": ["dev1@"], "dst": ["dev1@:*"] },
{ "action": "accept", "src": ["dev2"], "dst": ["dev2:*"] }, { "action": "accept", "src": ["dev2@"], "dst": ["dev2@:*"] },
{ "action": "accept", "src": ["admin1"], "dst": ["admin1:*"] }, { "action": "accept", "src": ["admin1@"], "dst": ["admin1@:*"] },
{ "action": "accept", "src": ["intern1"], "dst": ["intern1:*"] } { "action": "accept", "src": ["intern1@"], "dst": ["intern1@:*"] }
] ]
} }
``` ```

1
docs/ref/integration/web-ui.md
View file

@ -9,7 +9,6 @@ Headscale doesn't provide a built-in web interface but users may pick one from t
| Name | Repository Link | Description | | Name | Repository Link | Description |
| ---------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------ | | ---------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| headscale-webui | [Github](https://github.com/ifargle/headscale-webui) | A simple headscale web UI for small-scale deployments. |
| headscale-ui | [Github](https://github.com/gurucomputing/headscale-ui) | A web frontend for the headscale Tailscale-compatible coordination server | | headscale-ui | [Github](https://github.com/gurucomputing/headscale-ui) | A web frontend for the headscale Tailscale-compatible coordination server |
| HeadscaleUi | [GitHub](https://github.com/simcu/headscale-ui) | A static headscale admin ui, no backend environment required | | HeadscaleUi | [GitHub](https://github.com/simcu/headscale-ui) | A static headscale admin ui, no backend environment required |
| Headplane | [GitHub](https://github.com/tale/headplane) | An advanced Tailscale inspired frontend for headscale | | Headplane | [GitHub](https://github.com/tale/headplane) | An advanced Tailscale inspired frontend for headscale |

27
docs/setup/install/container.md
View file

@ -7,11 +7,14 @@
**It might be outdated and it might miss necessary steps**. **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. This documentation has the goal of showing a user how-to set up and run headscale in a container. A container runtime
[Docker](https://www.docker.com) is used as the reference container implementation, but there is no reason that it such as [Docker](https://www.docker.com) or [Podman](https://podman.io) is required. The container image can be found on
should not work with alternatives like [Podman](https://podman.io). The container image can be found on [Docker Hub](https://hub.docker.com/r/headscale/headscale) and [GitHub Container
[Docker Hub](https://hub.docker.com/r/headscale/headscale) and Registry](https://github.com/juanfont/headscale/pkgs/container/headscale). The container image URLs are:
[GitHub Container Registry](https://github.com/juanfont/headscale/pkgs/container/headscale).
- [Docker Hub](https://hub.docker.com/r/headscale/headscale): `docker.io/headscale/headscale:<VERSION>`
- [GitHub Container Registry](https://github.com/juanfont/headscale/pkgs/container/headscale):
`ghcr.io/juanfont/headscale:<VERSION>`
## Configure and run headscale ## Configure and run headscale
@ -36,7 +39,7 @@ should not work with alternatives like [Podman](https://podman.io). The containe
--volume "$(pwd)/run:/var/run/headscale" \ --volume "$(pwd)/run:/var/run/headscale" \
--publish 127.0.0.1:8080:8080 \ --publish 127.0.0.1:8080:8080 \
--publish 127.0.0.1:9090:9090 \ --publish 127.0.0.1:9090:9090 \
headscale/headscale:<VERSION> \ docker.io/headscale/headscale:<VERSION> \
serve serve
``` ```
@ -48,11 +51,9 @@ should not work with alternatives like [Podman](https://podman.io). The containe
A similar configuration for `docker-compose`: A similar configuration for `docker-compose`:
```yaml title="docker-compose.yaml" ```yaml title="docker-compose.yaml"
version: "3.7"
services: services:
headscale: headscale:
image: headscale/headscale:<VERSION> image: docker.io/headscale/headscale:<VERSION>
restart: unless-stopped restart: unless-stopped
container_name: headscale container_name: headscale
ports: ports:
@ -126,11 +127,11 @@ tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
## Debugging headscale running in Docker ## 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 headscale running in the Docker container, you can use the `-debug` variant, for example `headscale/headscale:x.x.x-debug`. The Headscale container image is based on a "distroless" image that does not contain a shell or any other debug tools. If you need to debug headscale running in the Docker container, you can use the `-debug` variant, for example `docker.io/headscale/headscale:x.x.x-debug`.
### Running the debug Docker container ### 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. To run the debug Docker container, use the exact same commands as above, but replace `docker.io/headscale/headscale:x.x.x` with `docker.io/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 ### Executing commands in the debug container
@ -141,13 +142,13 @@ Additionally, the debug container includes a minimalist Busybox shell.
To launch a shell in the container, use: To launch a shell in the container, use:
```shell ```shell
docker run -it headscale/headscale:x.x.x-debug sh docker run -it docker.io/headscale/headscale:x.x.x-debug sh
``` ```
You can also execute commands directly, such as `ls /ko-app` in this example: You can also execute commands directly, such as `ls /ko-app` in this example:
```shell ```shell
docker run headscale/headscale:x.x.x-debug ls /ko-app docker run docker.io/headscale/headscale:x.x.x-debug ls /ko-app
``` ```
Using `docker exec -it` allows you to run commands in an existing container. Using `docker exec -it` allows you to run commands in an existing container.