From dfaf120f2a1cd8ee7ab1c437062894402f3eb349 Mon Sep 17 00:00:00 2001 From: Kristoffer Dalby Date: Fri, 27 Mar 2026 09:26:04 +0000 Subject: [PATCH] docs: add development builds install page Move the container image and binary download details from the README into a dedicated documentation page at setup/install/main. This gives development builds a proper home in the docs site alongside the other install methods. The README now links to the docs page instead. --- README.md | 19 ++----------- docs/setup/install/main.md | 58 ++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 62 insertions(+), 16 deletions(-) create mode 100644 docs/setup/install/main.md diff --git a/README.md b/README.md index 68626814..69403380 100644 --- a/README.md +++ b/README.md @@ -67,22 +67,9 @@ For NixOS users, a module is available in [`nix/`](./nix/). ## Builds from `main` -Each push to `main` automatically builds container images and binaries. -These track the latest development state and are not versioned releases. - -**Container images** (multi-arch: amd64, arm64): - -- `ghcr.io/juanfont/headscale:main-` -- `docker.io/headscale/headscale:main-` - -**Binary downloads** (latest successful build via [nightly.link](https://nightly.link/juanfont/headscale/workflows/container-main/main)): - -| OS | Arch | Download | -| ----- | ----- | -------------------------------------------------------------------------------------------------------------------------- | -| Linux | amd64 | [headscale-linux-amd64](https://nightly.link/juanfont/headscale/workflows/container-main/main/headscale-linux-amd64.zip) | -| Linux | arm64 | [headscale-linux-arm64](https://nightly.link/juanfont/headscale/workflows/container-main/main/headscale-linux-arm64.zip) | -| macOS | amd64 | [headscale-darwin-amd64](https://nightly.link/juanfont/headscale/workflows/container-main/main/headscale-darwin-amd64.zip) | -| macOS | arm64 | [headscale-darwin-arm64](https://nightly.link/juanfont/headscale/workflows/container-main/main/headscale-darwin-arm64.zip) | +Development builds from the `main` branch are available as container images and +binaries. See the [development builds](https://headscale.net/stable/setup/install/main/) +documentation for details. ## Talks diff --git a/docs/setup/install/main.md b/docs/setup/install/main.md new file mode 100644 index 00000000..babb35ba --- /dev/null +++ b/docs/setup/install/main.md @@ -0,0 +1,58 @@ +# Development builds + +!!! warning + + Development builds are created automatically from the latest `main` branch + and are **not versioned releases**. They may contain incomplete features, + breaking changes, or bugs. Use them for testing only. + +Each push to `main` produces container images and cross-compiled binaries. +Container images are multi-arch (amd64, arm64) and use the same distroless +base image as official releases. + +## Container images + +Images are available from both Docker Hub and GitHub Container Registry, tagged +with the short commit hash of the build (e.g. `main-abc1234`): + +- Docker Hub: `docker.io/headscale/headscale:main-` +- GitHub Container Registry: `ghcr.io/juanfont/headscale:main-` + +To find the latest available tag, check the +[GitHub Actions workflow](https://github.com/juanfont/headscale/actions/workflows/container-main.yml) +or the [GitHub Container Registry package page](https://github.com/juanfont/headscale/pkgs/container/headscale). + +For example, to run a specific development build: + +```shell +docker run \ + --name headscale \ + --detach \ + --read-only \ + --tmpfs /var/run/headscale \ + --volume "$(pwd)/config:/etc/headscale:ro" \ + --volume "$(pwd)/lib:/var/lib/headscale" \ + --publish 127.0.0.1:8080:8080 \ + --publish 127.0.0.1:9090:9090 \ + --health-cmd "CMD headscale health" \ + docker.io/headscale/headscale:main- \ + serve +``` + +See [Running headscale in a container](./container.md) for full container setup instructions. + +## Binaries + +Pre-built binaries from the latest successful build on `main` are available +via [nightly.link](https://nightly.link/juanfont/headscale/workflows/container-main/main): + +| OS | Arch | Download | +| ----- | ----- | -------------------------------------------------------------------------------------------------------------------------- | +| Linux | amd64 | [headscale-linux-amd64](https://nightly.link/juanfont/headscale/workflows/container-main/main/headscale-linux-amd64.zip) | +| Linux | arm64 | [headscale-linux-arm64](https://nightly.link/juanfont/headscale/workflows/container-main/main/headscale-linux-arm64.zip) | +| macOS | amd64 | [headscale-darwin-amd64](https://nightly.link/juanfont/headscale/workflows/container-main/main/headscale-darwin-amd64.zip) | +| macOS | arm64 | [headscale-darwin-arm64](https://nightly.link/juanfont/headscale/workflows/container-main/main/headscale-darwin-arm64.zip) | + +After downloading, make the binary executable and follow the +[standalone binary installation](./official.md#using-standalone-binaries-advanced) +instructions for setting up the service. diff --git a/mkdocs.yml b/mkdocs.yml index 2d92f140..ffaa43b3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -170,6 +170,7 @@ nav: - Community packages: setup/install/community.md - Container: setup/install/container.md - Build from source: setup/install/source.md + - Development builds: setup/install/main.md - Upgrade: setup/upgrade.md - Usage: - Getting started: usage/getting-started.md