1
0
mirror of https://github.com/juanfont/headscale.git synced 2024-12-29 19:27:48 +00:00
nblock 8c7d8ee34f
Restructure headscale documentation ()
* 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: 

* Use hosts in acl documentation

thx @efficacy38 for noticing this

Ref: 

* Use mkdocs-macros to set headscale version once
2024-10-10 15:24:04 +02:00

5.0 KiB

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 is used as the reference container implementation, but there is no reason that it should not work with alternatives like Podman. The Docker image can be found on Docker Hub here.

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 database:

    mkdir -p ./headscale/config
    cd ./headscale
    
  2. 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 for details.

    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.

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

    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

    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
    
  4. Verify headscale is running:

    Follow the container logs:

    docker logs --follow headscale
    

    Verify running containers:

    docker ps
    

    Verify headscale is available:

    curl http://127.0.0.1:9090/metrics
    
  5. Create a user (tailnet):

    docker exec -it headscale \
      headscale users create myfirstuser
    

Register a machine (normal login)

On a client machine, execute the tailscale login command:

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:

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:

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:

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.