Restructure headscale documentation (#2163)

* Setup mkdocs-redirects * Restructure existing documentation * Move client OS support into the documentation * Move existing Client OS support table into its own documentation page * Link from README.md to the rendered documentation * Document minimum Tailscale client version * Reuse CONTRIBUTING.md" in the documentation * Include "CONTRIBUTING.md" from the repository root * Update FAQ and index page and link to the contributing docs * Add configuration reference * Add a getting started page and explain the first steps with headscale * Use the existing "Using headscale" sections and combine them into a single getting started guide with a little bit more explanation. * Explain how to get help from the command line client. * Remove duplicated sections from existing installation guides * Document requirements and assumptions * Document packages provided by the community * Move deb install guide to official releases * Move manual install guide to official releases * Move container documentation to setup section * Move sealos documentation to cloud install page * Move OpenBSD docs to build from source * Simplify DNS documentation * Add sponsor page * Add releases page * Add features page * Add help page * Add upgrading page * Adjust mkdocs nav * Update wording Use the term headscale for the project, Headscale on the beginning of a sentence and `headscale` when refering to the CLI. * Welcome to headscale * Link to existing documentation in the FAQ * Remove the goal header and use the text as opener * Indent code block in OIDC * Make a few pages linter compatible Also update ignored files for prettier * Recommend HTTPS on port 443 Fixes: #2164 * Use hosts in acl documentation thx @efficacy38 for noticing this Ref: #1863 * Use mkdocs-macros to set headscale version once
2024-10-10 15:24:04 +02:00 · 2024-10-10 15:24:04 +02:00 · 8c7d8ee34f
commit 8c7d8ee34f
parent b3cda08af6
41 changed files with 865 additions and 940 deletions
--- a/docs/setup/install/container.md
+++ b/docs/setup/install/container.md
@ -0,0 +1,155 @@
+# 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**.
+
+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 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 configuration and the [SQLite](https://www.sqlite.org/) database:
+
+    ```shell
+    mkdir -p ./headscale/config
+    cd ./headscale
+    ```
+
+1.  Download the example configuration for your chosen version and save it as: `/etc/headscale/config.yaml`. Adjust the
+    configuration to suit your local environment. See [Configuration](../../ref/configuration.md) for details.
+
+    ```shell
+    sudo mkdir -p /etc/headscale
+    sudo nano /etc/headscale/config.yaml
+    ```
+
+    Alternatively, you can mount `/var/lib` and `/var/run` from your host system by adding
+    `--volume $(pwd)/lib:/var/lib/headscale` and `--volume $(pwd)/run:/var/run/headscale`
+    in the next step.
+
+1.  Start the headscale server while working in the host headscale directory:
+
+    ```shell
+    docker run \
+      --name headscale \
+      --detach \
+      --volume $(pwd)/config:/etc/headscale/ \
+      --publish 127.0.0.1:8080:8080 \
+      --publish 127.0.0.1:9090:9090 \
+      headscale/headscale:<VERSION> \
+      serve
+    ```
+
+    Note: 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/` under `/etc/headscale`, forward port 8080 out of the container so the
+    headscale instance becomes available and then detach so headscale runs in the background.
+
+    Example `docker-compose.yaml`
+
+    ```yaml
+    version: "3.7"
+
+    services:
+      headscale:
+        image: headscale/headscale:<VERSION>
+        restart: unless-stopped
+        container_name: headscale
+        ports:
+          - "127.0.0.1:8080:8080"
+          - "127.0.0.1:9090:9090"
+        volumes:
+          # Please change <CONFIG_PATH> to the fullpath of the config folder just created
+          - <CONFIG_PATH>:/etc/headscale
+        command: serve
+    ```
+
+1.  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
+    ```
+
+1.  Create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)):
+
+    ```shell
+    docker exec -it headscale \
+      headscale users create myfirstuser
+    ```
+
+### Register a machine (normal login)
+
+On a client machine, execute the `tailscale` login command:
+
+```shell
+tailscale up --login-server YOUR_HEADSCALE_URL
+```
+
+To register a machine when running headscale in a container, take the headscale command and pass it to the container:
+
+```shell
+docker exec -it headscale \
+  headscale nodes register --user myfirstuser --key <YOUR_MACHINE_KEY>
+```
+
+### Register machine using a pre authenticated key
+
+Generate a key using the command line:
+
+```shell
+docker exec -it headscale \
+  headscale preauthkeys create --user myfirstuser --reusable --expiration 24h
+```
+
+This will return a pre-authenticated key that can be used to connect a node to headscale during the `tailscale` command:
+
+```shell
+tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
+```
+
+## 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 your application running in the Docker container, you can use the `-debug` variant, for example `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.
+
+### Executing commands in the debug container
+
+The default command in the debug container is to run `headscale`, which is located at `/ko-app/headscale` inside the container.
+
+Additionally, the debug container includes a minimalist Busybox shell.
+
+To launch a shell in the container, use:
+
+```
+docker run -it headscale/headscale:x.x.x-debug sh
+```
+
+You can also execute commands directly, such as `ls /ko-app` in this example:
+
+```
+docker run headscale/headscale:x.x.x-debug ls /ko-app
+```
+
+Using `docker exec -it` allows you to run commands in an existing container.