From 4e886c1a5bc441796710a14203771e201ce3cbc4 Mon Sep 17 00:00:00 2001
From: Igor Ramazanov <igor.ramazanov@magine.com>
Date: Wed, 12 Mar 2025 13:32:02 +0000
Subject: [PATCH] docs: improve `Nix` documentation

* Reflect recent changes.
* Link `Nix` in README
---
 README.md   |  8 ++++++++
 docs/Nix.md | 57 ++++++++++++++++++++++++++++++++++++++++-------------
 2 files changed, 51 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index d0125c1..ec71078 100644
--- a/README.md
+++ b/README.md
@@ -74,4 +74,12 @@ There are 2 ways to deploy Headplane:
     >
 </picture>
 
+### NixOS Deployment
+Integration with Nix provided:
+* development environment
+* building packages
+* NixOS module
+
+See [./docs/Nix.md](./docs/Nix.md) for details.
+
 > Copyright (c) 2025 Aarnav Tale
diff --git a/docs/Nix.md b/docs/Nix.md
index a0ce77b..12f3c18 100644
--- a/docs/Nix.md
+++ b/docs/Nix.md
@@ -28,8 +28,15 @@ git+file:///home/igor/personal/headplane?ref=refs/heads/nix&rev=2d78a95a0648a377
         └───headplane-agent: package 'hp_agent-0.5.3-SNAPSHOT'
 ```
 
+## NixOS module options
+Defined as `services.headplane.*`, check the `./nix/` directory for details.
+
 ## Usage
 
+1. Add the `github:tale/headplane` flake input.
+2. Import a default overlay to add `pkgs.headplane` and `pkgs.headplane-agent`.
+3. Import NixOS module for `services.headplane.*`.
+
 ```nix
 # Your flake.nix
 {
@@ -56,36 +63,58 @@ git+file:///home/igor/personal/headplane?ref=refs/heads/nix&rev=2d78a95a0648a377
           nixpkgs.overlays = [ headplane.overlays.default ];
         }
         {
-          {config, pkgs, ...}: {
-            services.headplane = let
-              headscaleConfig =
-                (pkgs.formats.yaml {}).generate
-                "headscale-for-headplane.yml"
-                config.services.headscale.settings;
-            in {
+          {config, pkgs, ...}:
+          let
+            format = pkgs.formats.yaml {};
+
+            # A workaround generate a valid Headscale config accepted by Headplane when `config_strict == true`.
+            settings = lib.recursiveUpdate config.services.headscale.settings {
+              acme_email = "/dev/null";
+              tls_cert_path = "/dev/null";
+              tls_key_path = "/dev/null";
+              policy.path = "/dev/null";
+              oidc.client_secret_path = "/dev/null";
+            };
+
+            headscaleConfig = format.generate "headscale.yml" settings;
+          in {
+            services.headplane = {
               enable = true;
-              agent.enable = false;
+              agent = {
+                # As an example only.
+                # Headplane Agent hasn't yet been ready at the moment of writing the doc.
+                enable = true;
+                settings = {
+                  HEADPLANE_AGENT_DEBUG = true;
+                  HEADPLANE_AGENT_HOSTNAME = "localhost";
+                  HEADPLANE_AGENT_TS_SERVER = "https://example.com";
+                  HEADPLANE_AGENT_TS_AUTHKEY = "xxxxxxxxxxxxxx";
+                  HEADPLANE_AGENT_HP_SERVER = "https://example.com/admin/dns";
+                  HEADPLANE_AGENT_HP_AUTHKEY = "xxxxxxxxxxxxxx";
+                };
+              };
               settings = {
                 server = {
                   host = "127.0.0.1";
                   port = 3000;
-                  cookie_secret = "replace me";
+                  cookie_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
                   cookie_secure = true;
                 };
                 headscale = {
                   url = "https://example.com";
                   config_path = "${headscaleConfig}";
-                  config_strict = false;
+                  config_strict = true;
                 };
                 integration.proc.enabled = true;
                 oidc = {
-                  issuer = "https://authelia.example.com";
+                  issuer = "https://oidc.example.com";
                   client_id = "headplane";
-                  client_secret = "replace me";
+                  client_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
                   disable_api_key_login = true;
+                  # Might needed when integrating with Authelia.
                   token_endpoint_auth_method = "client_secret_basic";
-                  headscale_api_key = "replace me";
-                  redirect_uri = "https://authelia.example.com/admin/oidc/callback";
+                  headscale_api_key = "xxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
+                  redirect_uri = "https://oidc.example.com/admin/oidc/callback";
                 };
               };
             };