chore: simplify documentation

tale · Jul 8, 2024 · bda151f · bda151f
1 parent 6d41185
commit bda151f
Show file tree

Hide file tree

Showing 5 changed files with 285 additions and 146 deletions.
diff --git a/docs/Advanced-Integration.md b/docs/Advanced-Integration.md
@@ -1,5 +1,11 @@
 # Advanced Integration
 
+The advanced integration methods unlock the full capabilities of Headplane.
+This is the closest you can get to the SaaS experience if you were paying for
+Tailscale.
+
+### Configuration Management
+
 <picture>
     <source
         media="(prefers-color-scheme: dark)"
@@ -15,21 +21,18 @@
     >
 </picture>
 
-With the advanced integration it's possible to control Access Control Lists (ACLs) and the Headscale configuration via the Headplane UI.
-Every single aspect of this integration is optional, meaning you can only use what you want.
-Additionally, with an integration provider, you can automatically reload the configuration or ACLs when they are changed.
-
-## Configuration Editing
+The advanced integration allows you to manage the Headscale configuration via
+the Headplane UI. When the configuration is available for editing, the `DNS`
+and `Settings` tabs will become available. When using the Docker or Kubernetes
+integration, changes to the configuration file will be automatically applied
+to Headscale.
 
-When the configuration file is available to Headplane, the `DNS` and `Settings` tabs will become functional.
-Similar to the Tailscale UI, you'll be able to edit the configuration without needing to manually edit the file.
-Headscale will read the file from the path given in the `CONFIG_FILE` environment variable.
-By default this is set to `/etc/headscale/config.yaml`.
+> By default, the configuration file is read from `/etc/headscale/config.yaml`.
+This can be overridden by setting the `CONFIG_FILE` environment variable. Any
+variables including `HEADSCALE_URL`, `OIDC_CLIENT_ID`, `OIDC_ISSUER`, and
+`OIDC_CLIENT_SECRET` will take priority over the configuration file.
 
-> One important think to note is that environment variables always take priority over the configuration file.
-> The `HEADSCALE_URL`, `OIDC_CLIENT_ID`, `OIDFC_ISSUER`, and `OIDC_CLIENT_SECRET` will be preferred over the configuration file if available.
-
-## Access Control Lists (ACLs)
+### Access Control Lists (ACLs)
 
 <picture>
     <source
@@ -46,126 +49,23 @@ By default this is set to `/etc/headscale/config.yaml`.
     >
 </picture>
 
-Headplane will enable the `Access Controls` tab if it is able to read an ACL file from Headscale.<br>
-The ACL file path is read from the following sources in order of priority:
-
-- **Environment Variable**: If you set the `ACL_FILE` environment variable, Headplane will read the file from that path.
-- **Configuration Integration**: If you've set this up, then Headplane will read the `acl_policy_path` key from the configuration file.
-
-## Automatic Configuration Reload
+The advanced integration allows you to manage the ACLs via the Headplane UI.
+When the ACL file is available for editing, the `Access Controls` tab will
+become available. All of the integrations support automatic reloading of the
+ACLs when the file is changed.
 
-When the configuration file is changed, Headscale will need to be restarted to apply the changes.
-Similarly, when the ACL file is changed, Headscale will need to be sent a `SIGHUP` signal to reload the ACLs.
-Currently there are 2 integration providers that can do this for you:
+> By default, the ACL file is read from `/etc/headscale/acl_policy.json`. This
+can be overridden by setting the `ACL_FILE` environment variable and is also
+overriden by the `acl_policy_path` key in the configuration file if set.
 
-### Docker Integration
-
-To enable the Docker integration, set `HEADSCALE_INTEGRATION=docker` in the environment variables.
-Additionally, you'll need to pass in the `HEADSCALE_CONTAINER` environment variable.
-This should be either the name or ID of the Headscale container (you can retrieve this using `docker ps`).
-If the other integrations aren't setup, then Headplane will automatically disable the Docker integration.
-
-By default the integration will check for `/var/run/docker.sock`, however you can override this by
-setting the `DOCKER_SOCK` environment variable if you use a different configuration than the default.
-When setting `DOCKER_SOCK`, you'll need to include the protocol (e.g., `unix://` or `tcp://`).
-Headplane currently does not support the HTTPS protocol for the Docker socket.
-
-#### Example Docker Deployment
+## Deployment
 
 Requirements:
 - Headscale 0.23 alpha or later
 - Headscale and Headplane need a Reverse Proxy (NGINX, Traefik, Caddy, etc)
-- Headscale needs to be running in a docker container
-
-Here's a good Docker Compose example:
-```yaml
-version: '3.8'
-services:
-  headscale:
-    image: 'headscale/headscale:0.23.0-alpha5'
-    container_name: 'headscale'
-    restart: 'unless-stopped'
-    command: 'serve'
-    volumes:
-      - './data:/var/lib/headscale'
-      - './configs:/etc/headscale'
-    ports:
-      - '8080:8080'
-    environment:
-      TZ: 'America/New_York'
-  headplane:
-    container_name: headplane
-    image: ghcr.io/tale/headplane:latest
-    restart: unless-stopped
-    volumes:
-      - './data:/var/lib/headscale'
-      - './configs:/etc/headscale'
-      - '/var/run/docker.sock:/var/run/docker.sock:ro'
-    ports:
-      - '3000:3000'
-    environment:
-      # This is always required for Headplane to work
-      COOKIE_SECRET: 'abcdefghijklmnopqrstuvwxyz'
-
-      HEADSCALE_INTEGRATION: 'docker'
-      HEADSCALE_CONTAINER: 'headscale'
-      DISABLE_API_KEY_LOGIN: 'true'
-      HOST: '0.0.0.0'
-      PORT: '3000'
-
-      # Overrides the configuration file values if they are set in config.yaml
-      # If you want to share the same OIDC configuration you do not need this
-      OIDC_CLIENT_ID: 'headscale'
-      OIDC_ISSUER: 'https://sso.example.com'
-      OIDC_CLIENT_SECRET: 'super_secret_client_secret'
-
-      # This NEEDS to be set with OIDC, regardless of what's in the config
-      # This needs to be a very long-lived (999 day) API key used to create
-      # shorter ones for OIDC and allow the OIDC functionality to work
-      ROOT_API_KEY: 'abcdefghijklmnopqrstuvwxyz'
-```
-
-> For a breakdown of each configuration variable, please refer to the [Configuration](/docs/Configuration.md) guide. 
-> It explains what each variable does, how to configure them, and what the default values are.
-
-You may also choose to run it natively with the distributed binaries on the releases page.
-You'll need to manage running this yourself, and I would recommend making a `systemd` unit.
-
-### Native Linux Integration (Beta)
-
-The native integration for Linux relies on the `/proc` directory to locate the Headscale process.
-To enable it, set the `HEADSCALE_INTEGRATION=proc` value in the environment variables.
-Because of the way this integration works, it only supports automatically reloading ACLs.
-It's still very experimental and may not work in all environments.
-
-## Configuration Scenarios
-
-Since the configuration is fairly modular you can have a variety of different setups.
-This mostly applies to the Docker integration since the native integration isn't fully featured yet.
-Here are a few examples to inspire you and show you what can work and what can't:
-
-#### Full Integration
-Headscale runs in a container, Headplane can run in either a container or natively.
-Headplane is able to manage the configuration file and ACLs that Headscale uses.
-When changes happen, the Docker integration will automatically reload the configuration and ACLs.
-
-> Note that the full integration currently isn't possible if Headscale isn't running in a container.
-
-#### Configuration Only
-Headscale and Headplane can either run in containers or natively.
-Headplane is able to manage the configuration file and ACLs that Headscale uses.
-When changes are made, Headscale will need to be manually restarted to apply the changes.
-
-#### ACL Only
-Headscale and Headplane can either run in containers or natively.
-Headplane is able to manage the ACLs that Headscale uses.
-When changes are made, Headscale will need to be sent a `SIGHUP` to reload the ACLs.
-In this scenario, Headplane does not have access to the configuration file.
 
-#### Read-Only Configuration or ACLs
-If the configuration or ACLs are read-only, Headplane will not be able to manage them.
-Instead you'll only be able to view the configurations on the UI and need to edit them manually.
+Currently there are 3 integration providers that can do this for you:
+- [Docker Integration](/docs/integration/Docker.md)
+- [Kubernetes Integration](/docs/integration/Kubernetes.md)
+- [Native Linux Integration](/docs/integration/Native.md)
 
-#### No Integration
-If no integration is setup, Headplane will not be able to manage the configuration or ACLs.
-This is the simplest setup by far, however it also heavily reduces the capabilities of Headplane.
diff --git a/docs/Basic-Integration.md b/docs/Basic-Integration.md
@@ -1,24 +1,31 @@
 # Basic Integration
 
-The basic integration is not able to offer advanced features such as:
-- Automatic management of Access Control Lists (ACLs)
-- Management of DNS settings for your tailnet
-- Management of the Headscale configuration
+The basic integration is the simplest way to get started with Headplane.
+It's more of a preview and is heavily limited in the features it can offer
+when compared to the [Advanced Integration](/docs/Advanced-Integration.md).
 
-In order to support these features please refer to the [Advanced Integration](./docs/Advanced-Integration.md) guide.
-Note that in order to use this deployment strategy you need to run Headscale in a Docker container.
+> Note that the Advanced integration is the recommend way to run
+Headplane in a production environment.
+
+## Limitations
+- No automatic management of Access Control Lists (ACLs)
+- No management of DNS settings for your tailnet
+- No capability to edit the configuration
+- Limited support for OIDC authentication
 
 ## Deployment
 
 Requirements:
 - Headscale 0.23 alpha or later
 - Headscale and Headplane need a Reverse Proxy (NGINX, Traefik, Caddy, etc)
 
-Headplane is currently best run in a Docker container due to the easy configuration.
-Here's a very basic `docker-compose.yaml` file that utilizes each configuration variable.
+Docker heavily simplifies the deployment process, but this process can be
+adopted to run natively. Follow the first section of the deployment guide
+in the [Native Integration](/docs/integration/Native.md#deployment) for a
+bare-metal or virtual machine deployment.
 
+Here is a simple Docker Compose deployment:
 ```yaml
-version: '3.8'
 services:
   headplane:
     container_name: headplane
@@ -42,12 +49,7 @@ services:
       PORT: '3000'
 ```
 
-> For a breakdown of each configuration variable, please refer to the [Configuration](/docs/Configuration.md) guide. 
-> It explains what each variable does, how to configure them, and what the default values are.
-
-You may also choose to run it natively with the distributed binaries on the releases page.
-You'll need to manage running this yourself, and I would recommend making a `systemd` unit.
-
-## ACL Configuration
-If you would like to get the web ACL configuration working, you'll need to pass the `ACL_FILE` environment variable.
-This should point to the path of the ACL file on the Headscale server (ie. `ACL_FILE=/etc/headscale/acl_policy.json`).
+> For a breakdown of each configuration variable, please refer to the
+[Configuration](/docs/Configuration.md) guide. 
+> It explains what each variable does, how to configure them, and what the
+default values are.
diff --git a/docs/integration/Docker.md b/docs/integration/Docker.md
@@ -0,0 +1,86 @@
+## Docker Integration
+
+The Docker integration allows you to run Headplane and Headscale separately
+in a dockerized environment. It allows you to unlock full functionality such as
+automatic reloading of ACLs, DNS management, and Headscale configuration
+management.
+
+### Deployment
+
+> When running with the Docker integration, it's assumed that both Headscale and
+Headplane will run as containers. If you are running Headscale natively, then
+refer to the [Native Integration](/docs/integration/Native.md) guide.
+
+To enable the Docker integration, set the `HEADSCALE_INTEGRATION` environment
+variable to `docker`. You'll also need to supply `HEADSCALE_CONTAINER` with the
+name or ID of the Headscale container.
+
+By default Headplane uses `unix:///var/run/docker.sock` to connect to Docker.
+This can be overridden by setting the `DOCKER_SOCK` environment variable. For
+example, a remote socket would be `tcp://<my-remote-host>:2375`. When setting
+the variable, you'll need to specify the protocol (`unix://` or `tcp://`).
+
+> The `DOCKER_SOCK` variable does not support the HTTPS protocol.
+
+To enable the Docker integration, set `HEADSCALE_INTEGRATION=docker` in the environment variables.
+Additionally, you'll need to pass in the `HEADSCALE_CONTAINER` environment variable.
+This should be either the name or ID of the Headscale container (you can retrieve this using `docker ps`).
+If the other integrations aren't setup, then Headplane will automatically disable the Docker integration.
+
+By default the integration will check for `/var/run/docker.sock`, however you can override this by
+setting the `DOCKER_SOCK` environment variable if you use a different configuration than the default.
+When setting `DOCKER_SOCK`, you'll need to include the protocol (e.g., `unix://` or `tcp://`).
+Headplane currently does not support the HTTPS protocol for the Docker socket.
+
+Here's an example deployment using Docker Compose (recommended). Keep in mind
+that you'll NEED to setup a reverse proxy and this is incomplete:
+```yaml
+services:
+  headscale:
+    image: 'headscale/headscale:0.23.0-alpha12'
+    container_name: 'headscale'
+    restart: 'unless-stopped'
+    command: 'serve'
+    volumes:
+      - './data:/var/lib/headscale'
+      - './configs:/etc/headscale'
+    ports:
+      - '8080:8080'
+    environment:
+      TZ: 'America/New_York'
+  headplane:
+    container_name: headplane
+    image: ghcr.io/tale/headplane:latest
+    restart: unless-stopped
+    volumes:
+      - './data:/var/lib/headscale'
+      - './configs:/etc/headscale'
+      - '/var/run/docker.sock:/var/run/docker.sock:ro'
+    ports:
+      - '3000:3000'
+    environment:
+      # This is always required for Headplane to work
+      COOKIE_SECRET: 'abcdefghijklmnopqrstuvwxyz'
+
+      HEADSCALE_INTEGRATION: 'docker'
+      HEADSCALE_CONTAINER: 'headscale'
+      DISABLE_API_KEY_LOGIN: 'true'
+      HOST: '0.0.0.0'
+      PORT: '3000'
+
+      # Overrides the configuration file values if they are set in config.yaml
+      # If you want to share the same OIDC configuration you do not need this
+      OIDC_CLIENT_ID: 'headscale'
+      OIDC_ISSUER: 'https://sso.example.com'
+      OIDC_CLIENT_SECRET: 'super_secret_client_secret'
+
+      # This NEEDS to be set with OIDC, regardless of what's in the config
+      # This needs to be a very long-lived (999 day) API key used to create
+      # shorter ones for OIDC and allow the OIDC functionality to work
+      ROOT_API_KEY: 'abcdefghijklmnopqrstuvwxyz'
+```
+
+> For a breakdown of each configuration variable, please refer to the
+[Configuration](/docs/Configuration.md) guide. 
+> It explains what each variable does, how to configure them, and what the
+default values are.