From fe285b4e6d4d058be9b02a6b03a308b591461522 Mon Sep 17 00:00:00 2001
From: Aarnav Tale <aarnavtale@icloud.com>
Date: Tue, 26 Mar 2024 11:25:55 -0400
Subject: [PATCH] feat: add documentation on deployment

---
 README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/README.md b/README.md
index 4968748..072c75a 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,70 @@ It's still very early in it's development, however these are some of the feature
 - [ ] Editable headscale configuration
 
 ## Deployment
+> The docker image is not available yet. For now you can build it locally with `docker build -t ghcr.io/tale/headplane:latest .`
+
+Currently I'd only recommend deploying this with Docker because environment variables are required.
+Here's a very basic `docker-compose.yaml` file that utilizes each configuration variable.
+
+```yaml
+version: '3.8'
+services:
+  headplane:
+    container_name: headplane
+    image: ghcr.io/tale/headplane:latest
+    restart: unless-stopped
+    environment:
+      HEADSCALE_URL: 'https://tailscale.example.com'
+      API_KEY: 'abcdefghijklmnopqrstuvwxyz'
+      COOKIE_SECRET: 'abcdefghijklmnopqrstuvwxyz'
+      OIDC_CLIENT_ID: 'headscale'
+      OIDC_ISSUER: 'https://sso.example.com'
+      OIDC_CLIENT_SECRET: 'super_secret_client_secret'
+      DISABLE_API_KEY_LOGIN: 'true'
+      HOST: '0.0.0.0'
+      PORT: '3000'
+```
+
+#### Required Variables
+
+- **`HEADSCALE_URL`**: The public URL of your Headscale server.
+- **`API_KEY`**: An API key used to issue new ones for sessions (keep expiry fairly long).
+- **`COOKIE_SECRET`**: A secret used to sign cookies (use a relatively long and random string).
+
+#### Optional Variables
+
+- **`HOST`**: The host to bind the server to (default: `0.0.0.0`).
+- **`PORT`**: The port to bind the server to (default: `3000`).
+
+### SSO/OpenID Connect
+If you want to use OpenID Connect for SSO, you'll need to provide these variables.
+Headplane will utilize the expiry of your tokens to determine the expiry of the session.
+
+- **`OIDC_ISSUER`**: The issuer URL of your OIDC provider.
+- **`OIDC_CLIENT_ID`**: The client ID of your OIDC provider.
+- **`OIDC_CLIENT_SECRET`**: The client secret of your OIDC provider.
+- **`DISABLE_API_KEY_LOGIN`**: If you want to disable API key login, set this to `true`.
+
+Here's what an example with Authelia would look like if you used the same client for both Headscale and Headplane.
+Keep in mind that the recommended deployment would be putting Headplane behind /admin on a reverse proxy.
+If you use a different domain than the Headscale server, you'll need to make sure that Headscale responds with CORS headers.
+
+```yaml
+- client_id: 'headscale'
+  client_name: 'Headscale and Headplane'
+  public: false
+  authorization_policy: 'two_factor'
+  redirect_uris:
+      - 'https://headscale.example.com/oidc/callback'
+      - 'https://headscale.example.com/admin/oidc/callback'
+  scopes:
+      - 'openid'
+      - 'profile'
+      - 'email'
+  userinfo_signed_response_alg: 'none'
+  client_secret: 'my_super_secret_client_secret'
+```
+
 Instructions for deploying this will come soon. It will utilize Docker to support advanced features.
 If you do want to fight with the environment variables right now, the image is `ghcr.io/tale/headplane:latest`