docs: fix nginx proxy_pass for "location /admin/" stanza

As-is, the nginx sample configuration maps the location from the
original URL (`/admin/`) to the location in the `pass_proxy` argument
`http://localhost:3000/` (`/`) .

Headplane does not have a route for `/`, so it returns a `404 Not Found`
with this configuration. Headplane _does_ have a route for `/admin/`. By
omitting the location portion of the `pass_proxy` argument, the location
from the original URL is used (c.f.
https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/#passing-a-request-to-a-proxied-server),
serving up the correct content.
This commit is contained in:
Seth Milliken
2026-01-25 18:37:31 -08:00
parent a710995f97
commit 573dd7e52e
+15 -11
View File
@@ -5,6 +5,7 @@ outline: [2, 3]
--- ---
# Native Mode # Native Mode
::: tip ::: tip
If you are looking to deploy with Docker, follow the If you are looking to deploy with Docker, follow the
[**Docker**](./docker.md) deployment guide. [**Docker**](./docker.md) deployment guide.
@@ -15,11 +16,12 @@ for Docker. This method is suitable for users who already run Headscale natively
or prefer to avoid containers. or prefer to avoid containers.
## Prerequisites ## Prerequisites
- A Linux-based operating system (e.g, Ubuntu, Debian, CentOS, Fedora) - A Linux-based operating system (e.g, Ubuntu, Debian, CentOS, Fedora)
- Go version 1.25.1 installed (only needed to build Headplane) - Go version 1.25.1 installed (only needed to build Headplane)
- Node.js version 22.16.x and [pnpm](https://pnpm.io/) version 10.4.x installed - Node.js version 22.16.x and [pnpm](https://pnpm.io/) version 10.4.x installed
- Headscale version 0.26.0 or later installed and running - Headscale version 0.26.0 or later installed and running
- A [completed configuration file](./index.md#configuration) for Headplane. - A [completed configuration file](./index.md#configuration) for Headplane.
Before building and running Headplane, ensure that the directory defined in Before building and running Headplane, ensure that the directory defined in
`server.data_path` in your configuration exists and is writable by the user who `server.data_path` in your configuration exists and is writable by the user who
@@ -32,6 +34,7 @@ sudo chown -R $(whoami):$(whoami) /var/lib/headplane
``` ```
## Building Headplane ## Building Headplane
Clone the Headplane repository, install dependencies, and build the project: Clone the Headplane repository, install dependencies, and build the project:
```bash ```bash
@@ -43,6 +46,7 @@ pnpm build
``` ```
## Running Headplane ## Running Headplane
Running Headplane is as straightforward as running `pnpm start` (or also Running Headplane is as straightforward as running `pnpm start` (or also
directly with `node build/server/index.js`). Headplane will look for a config directly with `node build/server/index.js`). Headplane will look for a config
file at `/etc/headplane/config.yaml` by default, but you can specify a different file at `/etc/headplane/config.yaml` by default, but you can specify a different
@@ -81,7 +85,7 @@ WantedBy=multi-user.target
To access Headplane, navigate to `http://localhost:3000/admin` in your web To access Headplane, navigate to `http://localhost:3000/admin` in your web
browser (replace `localhost` with your server's IP address or domain name if browser (replace `localhost` with your server's IP address or domain name if
not running locally). not running locally).
In order to log in, you'll need to supply a Headscale API key. You can create In order to log in, you'll need to supply a Headscale API key. You can create
one by running the following command within your Headscale environment: one by running the following command within your Headscale environment:
@@ -103,6 +107,7 @@ 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. custom A records, the tailnet domain name, and MagicDNS from the Headplane UI.
#### Prerequisites #### Prerequisites
Network management (and other configurable Headscale features) requires that Network management (and other configurable Headscale features) requires that
Headplane and Headscale both run on the same machine because Headplane needs Headplane and Headscale both run on the same machine because Headplane needs
@@ -114,11 +119,11 @@ Headplane and Headscale both run on the same machine because Headplane needs
Enabling network management is as simple as setting a few additional fields in Enabling network management is as simple as setting a few additional fields in
your Headplane configuration file: your Headplane configuration file:
| Field | Description | | Field | Description |
|---------------------|--------------------------------------------------------| | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| **`integration.proc.enabled`** | Set to `true` to enable process inspection. | | **`integration.proc.enabled`** | Set to `true` to enable process inspection. |
| **`headscale.config_path`** | Path to your Head**scale** configuration file (e.g., `/etc/headscale/config.yaml`). | | **`headscale.config_path`** | Path to your Head**scale** configuration file (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. | | `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 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 options in the UI navbar such as "DNS" and "Settings" where you can manage your
@@ -138,7 +143,6 @@ setup instructions and specifically follow the
[native mode configuration](../features/agent.md#native-mode-configuration) [native mode configuration](../features/agent.md#native-mode-configuration)
section to point Headplane to the correct agent location. section to point Headplane to the correct agent location.
### Single Sign-On (SSO) ### Single Sign-On (SSO)
Single Sign-On (SSO) authentication allows users to log in to Headplane using Single Sign-On (SSO) authentication allows users to log in to Headplane using
@@ -148,14 +152,14 @@ supports OpenID Connect (OIDC).
To get started with SSO, refer to the [SSO documentation](../features/sso.md) To get started with SSO, refer to the [SSO documentation](../features/sso.md)
for detailed setup instructions. for detailed setup instructions.
## Reverse Proxying ## 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 production. Additionally, putting Headscale beind the reverse proxy allows
you to access both services via the same domain and TLS certificate. you to access both services via the same domain and TLS certificate.
#### Configuration #### Configuration
::: tip ::: tip
If you are using a [custom path prefix](#custom-path-prefix) for Headplane, If you are using a [custom path prefix](#custom-path-prefix) for Headplane,
adjust the `/admin` paths in the examples below accordingly. adjust the `/admin` paths in the examples below accordingly.
@@ -205,7 +209,7 @@ server {
} }
location /admin/ { # Headplane is served under /admin location /admin/ { # Headplane is served under /admin
proxy_pass http://localhost:3000/; # Adjust if Headplane runs on a different port proxy_pass http://localhost:3000; # Adjust if Headplane runs on a different port
proxy_http_version 1.1; proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade; proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade; proxy_set_header Connection $connection_upgrade;