From 6d70497758840e67a836d1c33ff20017b66c2049 Mon Sep 17 00:00:00 2001 From: Aarnav Tale Date: Sat, 7 Mar 2026 15:15:05 -0500 Subject: [PATCH] revert: remove this useless contribution --- docs/install/docker.md | 118 +++++++++++++++++++++-------------------- 1 file changed, 60 insertions(+), 58 deletions(-) diff --git a/docs/install/docker.md b/docs/install/docker.md index e710df9..03f6f14 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -5,6 +5,7 @@ outline: [2, 3] --- # Docker Installation + ::: tip If you are not looking to deploy with Docker, follow the [**Native Mode**](./native-mode.md) deployment guide. @@ -15,13 +16,15 @@ easy, and works in most environments. It requires that Headscale is also running with Docker. ## Prerequisites + - Docker and Docker Compose - Headscale version 0.26.0 or later installed and running -- A [completed configuration file](/docker.md#configuration) for Headplane. - +- A [completed configuration file](./index.md#configuration) for Headplane. ## Installation + Running Headplane in with Docker is as simple as applying 1 compose file: + ```yaml services: headplane: @@ -29,10 +32,10 @@ services: container_name: headplane restart: unless-stopped ports: - - '3000:3000' + - "3000:3000" volumes: - - './config.yaml:/etc/headplane/config.yaml' - - './headplane-data:/var/lib/headplane' + - "./config.yaml:/etc/headplane/config.yaml" + - "./headplane-data:/var/lib/headplane" ``` It's important to mount your configuration file and also provide a persistent @@ -87,14 +90,15 @@ Network management allows you to configure Tailnet settings such as DNS servers, custom A records, the tailnet domain name, and MagicDNS from the Headplane UI. #### Prerequisites + Network management (and other configurable Headscale features) requires that Headplane and Headscale both run together in the same Docker machine. This is because Headplane needs the following permissions: - Access to read and write the Head**scale** configuration file through a shared -volume used by both Headscale and Headplane. + volume used by both Headscale and Headplane. - Access to the Docker socket (usually `/var/run/docker.sock`, you may also use -a proxy such as [Tecnativa/docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy)). + a proxy such as [Tecnativa/docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy)). #### Configuration @@ -108,25 +112,25 @@ services: container_name: headplane restart: unless-stopped ports: - - '3000:3000' + - "3000:3000" volumes: # Same as before - - '/path/to/your/config.yaml:/etc/headplane/config.yaml' - - '/path/to/data/storage:/var/lib/headplane' + - "/path/to/your/config.yaml:/etc/headplane/config.yaml" + - "/path/to/data/storage:/var/lib/headplane" # A shared path to the Headscale config file. It is important that the # path you mount this on matches `headscale.config_path` in your # Headplane config.yaml file. - - '/path/to/headscale/config.yaml:/etc/headscale/config.yaml' + - "/path/to/headscale/config.yaml:/etc/headscale/config.yaml" # If you are using dns.extra_records in Headscale (recommended), you # should also mount that file here so Headplane can read and write it. # Ensure that the path matches `headscale.dns_records_path` in your # Headplane config.yaml file. - - '/path/to/headscale/dns_records.json:/etc/headscale/dns_records.json' + - "/path/to/headscale/dns_records.json:/etc/headscale/dns_records.json" # Read-only access to the Docker socket (or a proxy) - - '/var/run/docker.sock:/var/run/docker.sock:ro' + - "/var/run/docker.sock:/var/run/docker.sock:ro" headscale: image: headscale/headscale:0.26.0 container_name: headscale @@ -136,14 +140,14 @@ services: # This label is absolutely necessary to help Headplane find Headscale. me.tale.headplane.target: headscale ports: - - '8080:8080' + - "8080:8080" volumes: # Notice how these are on the exact same path as the host for both # Headscale and Headplane! This is very important. - - '/path/to/headscale/config.yaml:/etc/headscale/config.yaml' - - '/path/to/headscale/dns_records.json:/etc/headscale/dns_records.json' + - "/path/to/headscale/config.yaml:/etc/headscale/config.yaml" + - "/path/to/headscale/dns_records.json:/etc/headscale/dns_records.json" - - '/path/to/headscale/data/storage:/var/lib/headscale' + - "/path/to/headscale/data/storage:/var/lib/headscale" ``` ::: info @@ -156,11 +160,11 @@ for more details on setting it up. You'll also need to enable a few fields in your Headplane configuration file: -| Field | Description | -|---------------------|--------------------------------------------------------| -| **`integration.docker.enabled`** | Set to `true` to enable Docker integration. | -| **`headscale.config_path`** | Path to your Head**scale** configuration file within the container (e.g., `/etc/headscale/config.yaml`). | -| `headscale.dns_records_path` | *Optional*. Refer to the [example configuration](https://github.com/tale/headplane/blob/main/config.example.yaml) for details. | +| Field | Description | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| **`integration.docker.enabled`** | Set to `true` to enable Docker integration. | +| **`headscale.config_path`** | Path to your Head**scale** configuration file within the container (e.g., `/etc/headscale/config.yaml`). | +| `headscale.dns_records_path` | _Optional_. Refer to the [example configuration](https://github.com/tale/headplane/blob/main/config.example.yaml) for details. | With these settings in place, restart Headplane. You should now see additional options in the UI navbar such as "DNS" and "Settings" where you can manage your @@ -187,10 +191,9 @@ supports OpenID Connect (OIDC). To get started with SSO, refer to the [SSO documentation](../features/sso.md) for detailed setup instructions. - ## Reverse Proxying -You *should* run Headplane behind a reverse proxy such as Nginx or Caddy in +You _should_ run Headplane behind a reverse proxy such as Nginx or Caddy in production. Additionally, putting Headscale beind the reverse proxy allows you to access both services via the same domain and TLS certificate. @@ -222,63 +225,62 @@ services: container_name: headplane restart: unless-stopped ports: - - '3000:3000' + - "3000:3000" volumes: - - '/path/to/your/config.yaml:/etc/headplane/config.yaml' - - '/path/to/data/storage:/var/lib/headplane' - - '/path/to/headscale/config.yaml:/etc/headscale/config.yaml' - - '/path/to/headscale/dns_records.json:/etc/headscale/dns_records.json' - - '/var/run/docker.sock:/var/run/docker.sock:ro' + - "/path/to/your/config.yaml:/etc/headplane/config.yaml" + - "/path/to/data/storage:/var/lib/headplane" + - "/path/to/headscale/config.yaml:/etc/headscale/config.yaml" + - "/path/to/headscale/dns_records.json:/etc/headscale/dns_records.json" + - "/var/run/docker.sock:/var/run/docker.sock:ro" labels: # Expose the admin UI at /admin - - 'traefik.enable=true' - - 'traefik.http.routers.headplane.rule=Host(`headscale.example.com`) && PathPrefix(`/admin`)' - - 'traefik.http.routers.headplane.entrypoints=websecure' - - 'traefik.http.routers.headplane.tls=true' + - "traefik.enable=true" + - "traefik.http.routers.headplane.rule=Host(`headscale.example.com`) && PathPrefix(`/admin`)" + - "traefik.http.routers.headplane.entrypoints=websecure" + - "traefik.http.routers.headplane.tls=true" headscale: image: headscale/headscale:0.26.0 container_name: headscale restart: unless-stopped command: serve ports: - - '8080:8080' + - "8080:8080" volumes: - - '/path/to/headscale/config.yaml:/etc/headscale/config.yaml' - - '/path/to/headscale/dns_records.json:/etc/headscale/dns_records.json' - - '/path/to/headscale/data/storage:/var/lib/headscale' + - "/path/to/headscale/config.yaml:/etc/headscale/config.yaml" + - "/path/to/headscale/dns_records.json:/etc/headscale/dns_records.json" + - "/path/to/headscale/data/storage:/var/lib/headscale" labels: - - 'me.tale.headplane.target=headscale' + - "me.tale.headplane.target=headscale" # Traefik labels to expose Headscale at headscale.example.com - - 'traefik.enable=true' - - 'traefik.http.routers.headscale.rule=Host(`headscale.example.com`)' - - 'traefik.http.routers.headscale.entrypoints=websecure' - - 'traefik.http.routers.headscale.tls=true' + - "traefik.enable=true" + - "traefik.http.routers.headscale.rule=Host(`headscale.example.com`)" + - "traefik.http.routers.headscale.entrypoints=websecure" + - "traefik.http.routers.headscale.tls=true" # This middleware is essential to ensuring Headplane works correctly - - 'traefik.http.routers.headscale.middlewares=cors' - - 'traefik.http.middlewares.cors.headers.accesscontrolallowheaders=*' - - 'traefik.http.middlewares.cors.headers.accesscontrolallowmethods=GET,POST,PUT' - - 'traefik.http.middlewares.cors.headers.accesscontrolalloworiginlist=https://headscale.example.com' - - 'traefik.http.middlewares.cors.headers.accesscontrolmaxage=100' - - 'traefik.http.middlewares.cors.headers.addvaryheader=true' + - "traefik.http.routers.headscale.middlewares=cors" + - "traefik.http.middlewares.cors.headers.accesscontrolallowheaders=*" + - "traefik.http.middlewares.cors.headers.accesscontrolallowmethods=GET,POST,PUT" + - "traefik.http.middlewares.cors.headers.accesscontrolalloworiginlist=https://headscale.example.com" + - "traefik.http.middlewares.cors.headers.accesscontrolmaxage=100" + - "traefik.http.middlewares.cors.headers.addvaryheader=true" # If you would optionally like to automatically redirect / to /admin - - 'traefik.http.routers.rewrite.rule=Host(`headscale.example.com`) && Path(`/`)' - - 'traefik.http.routers.rewrite.service=headscale' - - 'traefik.http.routers.rewrite.middlewares=rewrite' - - 'traefik.http.middlewares.rewrite.addprefix.prefix=/admin' + - "traefik.http.routers.rewrite.rule=Host(`headscale.example.com`) && Path(`/`)" + - "traefik.http.routers.rewrite.service=headscale" + - "traefik.http.routers.rewrite.middlewares=rewrite" + - "traefik.http.middlewares.rewrite.addprefix.prefix=/admin" traefik: image: traefik:v3.0 container_name: traefik restart: unless-stopped ports: - - '80:80' - - '443:443' + - "80:80" + - "443:443" volumes: # Example volumes/setup, please configure Traefik as needed - - '/var/run/docker.sock:/var/run/docker.sock:ro' - - '/path/to/certs/storage:/certs' + - "/var/run/docker.sock:/var/run/docker.sock:ro" + - "/path/to/certs/storage:/certs" ``` -