From 9a86ffc1022cef13b14ef62aed9d9e3f0e1450b1 Mon Sep 17 00:00:00 2001 From: nblock Date: Sun, 4 May 2025 21:55:08 +0200 Subject: [PATCH] Misc doc fixes (#2562) * 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. --- README.md | 8 ++++++-- docs/about/features.md | 4 +++- docs/ref/acls.md | 18 +++++++++--------- docs/ref/integration/web-ui.md | 1 - docs/setup/install/container.md | 27 ++++++++++++++------------- 5 files changed, 32 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 78c6a373..1114ae59 100644 --- a/README.md +++ b/README.md @@ -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. **Note:** Always select the same GitHub tag as the released version you use -to ensure you have the correct example configuration and documentation. -The `main` branch might contain unreleased changes. +to ensure you have the correct example configuration. The `main` branch might +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 diff --git a/docs/about/features.md b/docs/about/features.md index eb04bf74..22a4be62 100644 --- a/docs/about/features.md +++ b/docs/about/features.md @@ -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] Access control lists ([GitHub label "policy"](https://github.com/juanfont/headscale/labels/policy%20%F0%9F%93%9D)) - [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 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) + - [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)) - [x] Basic registration - [x] Update user profile from identity provider diff --git a/docs/ref/acls.md b/docs/ref/acls.md index c5f7d55e..f626a513 100644 --- a/docs/ref/acls.md +++ b/docs/ref/acls.md @@ -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 cannot be composed of groups "groups": { - "group:boss": ["boss"], - "group:dev": ["dev1", "dev2"], - "group:admin": ["admin1"], - "group:intern": ["intern1"] + "group:boss": ["boss@"], + "group:dev": ["dev1@", "dev2@"], + "group:admin": ["admin1@"], + "group:intern": ["intern1@"] }, // 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) @@ -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 // their own users. - { "action": "accept", "src": ["boss"], "dst": ["boss:*"] }, - { "action": "accept", "src": ["dev1"], "dst": ["dev1:*"] }, - { "action": "accept", "src": ["dev2"], "dst": ["dev2:*"] }, - { "action": "accept", "src": ["admin1"], "dst": ["admin1:*"] }, - { "action": "accept", "src": ["intern1"], "dst": ["intern1:*"] } + { "action": "accept", "src": ["boss@"], "dst": ["boss@:*"] }, + { "action": "accept", "src": ["dev1@"], "dst": ["dev1@:*"] }, + { "action": "accept", "src": ["dev2@"], "dst": ["dev2@:*"] }, + { "action": "accept", "src": ["admin1@"], "dst": ["admin1@:*"] }, + { "action": "accept", "src": ["intern1@"], "dst": ["intern1@:*"] } ] } ``` diff --git a/docs/ref/integration/web-ui.md b/docs/ref/integration/web-ui.md index 5c8d1b88..ec1fcb4d 100644 --- a/docs/ref/integration/web-ui.md +++ b/docs/ref/integration/web-ui.md @@ -9,7 +9,6 @@ Headscale doesn't provide a built-in web interface but users may pick one from t | 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 | | 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 | diff --git a/docs/setup/install/container.md b/docs/setup/install/container.md index 652ce80b..468f22bc 100644 --- a/docs/setup/install/container.md +++ b/docs/setup/install/container.md @@ -7,11 +7,14 @@ **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. -[Docker](https://www.docker.com) is used as the reference container implementation, but there is no reason that it -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 Registry](https://github.com/juanfont/headscale/pkgs/container/headscale). +This documentation has the goal of showing a user how-to set up and run headscale in a container. A container runtime +such as [Docker](https://www.docker.com) or [Podman](https://podman.io) is required. The container image can be found on +[Docker Hub](https://hub.docker.com/r/headscale/headscale) and [GitHub Container +Registry](https://github.com/juanfont/headscale/pkgs/container/headscale). The container image URLs are: + +- [Docker Hub](https://hub.docker.com/r/headscale/headscale): `docker.io/headscale/headscale:` +- [GitHub Container Registry](https://github.com/juanfont/headscale/pkgs/container/headscale): + `ghcr.io/juanfont/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" \ --publish 127.0.0.1:8080:8080 \ --publish 127.0.0.1:9090:9090 \ - headscale/headscale: \ + docker.io/headscale/headscale: \ serve ``` @@ -48,11 +51,9 @@ should not work with alternatives like [Podman](https://podman.io). The containe A similar configuration for `docker-compose`: ```yaml title="docker-compose.yaml" - version: "3.7" - services: headscale: - image: headscale/headscale: + image: docker.io/headscale/headscale: restart: unless-stopped container_name: headscale ports: @@ -126,11 +127,11 @@ tailscale up --login-server --authkey ## 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 -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 @@ -141,13 +142,13 @@ Additionally, the debug container includes a minimalist Busybox shell. To launch a shell in the container, use: ```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: ```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.