info about headless container and ui

Reviewed-on: coop-cloud/headscale#3

.env.sample

@@ -7,5 +7,21 @@ DOMAIN=headscale.example.com
 
 LETS_ENCRYPT_ENV=production
 
+COMPOSE_FILE="compose.yml"
+
 # Defines the base domain to create the hostnames for MagicDNS.
 BASE_DOMAIN=f0x.lan
+
+
+# set this to true to enable using the built-in DERP rather than tailscale's
+ENABLE_DERP=false
+
+# enable oidc
+# OIDC_ENABLED=1
+# OIDC_ISSUER=https://authentik.example
+# SECRET_OIDC_CLIENT_KEY_VERSION=v1
+# COMPOSE_FILE="$COMPOSE_FILE:compose.oidc.yml"
+
+# See https://git.coopcloud.tech/coop-cloud/backup-bot-two
+ENABLE_BACKUPS=true
+

.gitignore

@@ -1 +1,2 @@
 .envrc
+*~

README.md

@@ -1,15 +1,15 @@
 # headscale
 
-> One line description of the recipe
+> [Headscale](https://headscale.net/), the open-source, self-hosted, Tailscale VPN control server.
 
 <!-- metadata -->
 
 * **Category**: Apps
-* **Status**: 0
-* **Image**: [`headscale`](https://hub.docker.com/r/headscale), 4, upstream
-* **Healthcheck**: No
-* **Backups**: No
-* **Email**: No
+* **Status**: 3
+* **Image**: [`headscale/headscale`](https://hub.docker.com/r/headscale/headscale), 4, upstream
+* **Healthcheck**: Yes
+* **Backups**: Yes
+* **Email**: N/A
 * **Tests**: No
 * **SSO**: No
 
@@ -22,3 +22,23 @@
 * `abra app deploy <app-name>`
 
 For more, see [`docs.coopcloud.tech`](https://docs.coopcloud.tech).
+
+
+## Getting started using headscale 
+The recipe deploys two containers. 
+
+1. One is headscale itself. Note that it's a "distroless" container, so you can't enter with `bash` or `sh`, but you have to run the commands directly.
+
+> The headscale/headscale Docker container is based on a "distroless" image that does not contain a shell or any other debug tools. If you need to debug your application running in the Docker container, you can use the -debug variant, for example headscale/headscale:x.x.x-debug.
+> 
+> https://headscale.net/0.24.1/setup/install/container/#debugging-headscale-running-in-docker
+
+To run the command line do this:
+
+```bash
+abra app run yourapp.xyz app -- headscale help
+```
+
+2. The UI runs on `https://yourapp.xyz/web`, the UI is a mere frontend (a static site), so no data is saved on a server, so you will need to set URL and API-Key yourself on every client. Find more about the UI [here](https://github.com/gurucomputing/headscale-ui).
+
+For the usage of headscale itself, check the [offical docs](https://headscale.net/stable/usage/getting-started/).

abra.sh

@@ -1,3 +1,3 @@
 # Set any config versions here
 # Docs: https://docs.coopcloud.tech/maintainers/handbook/#manage-configs
-export CONFIG_YAML_VERSION=v3
+export CONFIG_YAML_VERSION=v4

compose.oidc.yml

@@ -0,0 +1,10 @@
+---
+services:
+  app:
+    secrets:
+      - oidc_client_key
+
+secrets:
+  oidc_client_key:
+    external: true
+    name: ${STACK_NAME}_oidc_client_key_${SECRET_OIDC_CLIENT_KEY_VERSION}

compose.yml

@@ -20,11 +20,10 @@ services:
         - "traefik.http.routers.${STACK_NAME}.rule=Host(`${DOMAIN}`${EXTRA_DOMAINS})"
         - "traefik.http.routers.${STACK_NAME}.entrypoints=web-secure"
         - "traefik.http.routers.${STACK_NAME}.tls.certresolver=${LETS_ENCRYPT_ENV}"
-        ## When you're ready for release, run "abra recipe sync <name>" to set this
         - "coop-cloud.${STACK_NAME}.version=0.1.0+v0.28"
-        ## Enable backups: https://docs.coopcloud.tech/maintainers/handbook/#how-do-i-configure-backuprestore
-        # - "backupbot.backup=true"
-        # - "backupbot.backup.path=/some/path"
+        # Enable backups: https://docs.coopcloud.tech/maintainers/handbook/#how-do-i-configure-backuprestore
+        - "backupbot.backup=${ENABLE_BACKUPS:-true}"
+        - "backupbot.backup.path=/var/lib/headscale"
     healthcheck:
       test: ["CMD", "headscale", "health"]
       interval: 30s
@@ -49,7 +48,6 @@ networks:
     external: true
 
 volumes:
-  # config:
   data:
 
 configs:

config.yaml.tmpl

@@ -75,7 +75,7 @@ derp:
   server:
     # If enabled, runs the embedded DERP server and merges it into the rest of the DERP config
     # The Headscale server_url defined above MUST be using https, DERP requires TLS to be in place
-    enabled: false
+    enabled: {{ env "ENABLE_DERP" }}
 
     # Region ID to use for the embedded DERP server.
     # The local DERP prevails if the region ID collides with other region ID coming from
@@ -326,76 +326,78 @@ unix_socket: /var/run/headscale/headscale.sock
 unix_socket_permission: "0770"
 
 # OpenID Connect
-# oidc:
-#   # Block startup until the identity provider is available and healthy.
-#   only_start_if_oidc_is_available: true
-#
-#   # OpenID Connect Issuer URL from the identity provider
-#   issuer: "https://your-oidc.issuer.com/path"
-#
-#   # Client ID from the identity provider
-#   client_id: "your-oidc-client-id"
-#
-#   # Client secret generated by the identity provider
-#   # Note: client_secret and client_secret_path are mutually exclusive.
-#   client_secret: "your-oidc-client-secret"
-#   # Alternatively, set `client_secret_path` to read the secret from the file.
-#   # It resolves environment variables, making integration to systemd's
-#   # `LoadCredential` straightforward:
-#   client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret"
-#
-#   # The amount of time a node is authenticated with OpenID until it expires
-#   # and needs to reauthenticate.
-#   # Setting the value to "0" will mean no expiry.
-#   expiry: 180d
-#
-#   # Use the expiry from the token received from OpenID when the user logged
-#   # in. This will typically lead to frequent need to reauthenticate and should
-#   # only be enabled if you know what you are doing.
-#   # Note: enabling this will cause `oidc.expiry` to be ignored.
-#   use_expiry_from_token: false
-#
-#   # The OIDC scopes to use, defaults to "openid", "profile" and "email".
-#   # Custom scopes can be configured as needed, be sure to always include the
-#   # required "openid" scope.
-#   scope: ["openid", "profile", "email"]
-#
-#   # Only verified email addresses are synchronized to the user profile by
-#   # default. Unverified emails may be allowed in case an identity provider
-#   # does not send the "email_verified: true" claim or email verification is
-#   # not required.
-#   email_verified_required: true
-#
-#   # Provide custom key/value pairs which get sent to the identity provider's
-#   # authorization endpoint.
-#   extra_params:
-#     domain_hint: example.com
-#
-#   # Only accept users whose email domain is part of the allowed_domains list.
-#   allowed_domains:
-#     - example.com
-#
-#   # Only accept users whose email address is part of the allowed_users list.
-#   allowed_users:
-#     - alice@example.com
-#
-#   # Only accept users which are members of at least one group in the
-#   # allowed_groups list.
-#   allowed_groups:
-#     - /headscale
-#
-#   # Optional: PKCE (Proof Key for Code Exchange) configuration
-#   # PKCE adds an additional layer of security to the OAuth 2.0 authorization code flow
-#   # by preventing authorization code interception attacks
-#   # See https://datatracker.ietf.org/doc/html/rfc7636
-#   pkce:
-#     # Enable or disable PKCE support (default: false)
-#     enabled: false
-#
-#     # PKCE method to use:
-#     # - plain: Use plain code verifier
-#     # - S256: Use SHA256 hashed code verifier (default, recommended)
-#     method: S256
+{{ if eq (env "OIDC_ENABLED") "1" }}
+oidc:
+  # Block startup until the identity provider is available and healthy.
+  only_start_if_oidc_is_available: true
+
+  # OpenID Connect Issuer URL from the identity provider
+  issuer: {{ env "OIDC_ISSUER" }}
+
+  # Client ID from the identity provider
+  client_id: "headscale"
+
+  # Client secret generated by the identity provider
+  # Note: client_secret and client_secret_path are mutually exclusive.
+  # client_secret: {{ env "OIDC_CLIENT_SECRET" }}
+  # Alternatively, set `client_secret_path` to read the secret from the file.
+  # It resolves environment variables, making integration to systemd's
+  # `LoadCredential` straightforward:
+  client_secret_path: "/run/secrets/oidc_client_key"
+
+  # The amount of time a node is authenticated with OpenID until it expires
+  # and needs to reauthenticate.
+  # Setting the value to "0" will mean no expiry.
+  expiry: 7d
+
+  # Use the expiry from the token received from OpenID when the user logged
+  # in. This will typically lead to frequent need to reauthenticate and should
+  # only be enabled if you know what you are doing.
+  # Note: enabling this will cause `oidc.expiry` to be ignored.
+  use_expiry_from_token: false
+
+  # The OIDC scopes to use, defaults to "openid", "profile" and "email".
+  # Custom scopes can be configured as needed, be sure to always include the
+  # required "openid" scope.
+  scope: ["openid", "profile", "email"]
+
+  # Only verified email addresses are synchronized to the user profile by
+  # default. Unverified emails may be allowed in case an identity provider
+  # does not send the "email_verified: true" claim or email verification is
+  # not required.
+  email_verified_required: true
+
+  # Provide custom key/value pairs which get sent to the identity provider's
+  # authorization endpoint.
+  # extra_params:
+  #  domain_hint: example.com
+
+  # Only accept users whose email domain is part of the allowed_domains list.
+  # allowed_domains:
+  #   - example.com
+
+  # Only accept users whose email address is part of the allowed_users list.
+  # allowed_users:
+  #   - alice@example.com
+
+  # Only accept users which are members of at least one group in the
+  # allowed_groups list.
+  # allowed_groups:
+  #   - /headscale
+
+  # Optional: PKCE (Proof Key for Code Exchange) configuration
+  # PKCE adds an additional layer of security to the OAuth 2.0 authorization code flow
+  # by preventing authorization code interception attacks
+  # See https://datatracker.ietf.org/doc/html/rfc7636
+  pkce:
+    # Enable or disable PKCE support (default: false)
+    enabled: true
+
+    # PKCE method to use:
+    # - plain: Use plain code verifier
+    # - S256: Use SHA256 hashed code verifier (default, recommended)
+    method: S256
+{{ end }}
 
 # Logtail configuration
 # Logtail is Tailscales logging and auditing infrastructure, it allows the

renovate.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "config:recommended"
+  ]
+}