From 0a21dce0d786c9c6ccc042e731487ec5fde4b1b3 Mon Sep 17 00:00:00 2001 From: William Mantly Date: Thu, 23 Jul 2026 03:17:40 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20surface=20the=20Directory=20doc=20?= =?UTF-8?q?=E2=80=94=20register=20in-app,=20link=20from=20UI=20and=20site?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/directory.md existed but was orphaned: not in the /docs registry, not linked anywhere. Now: - registered as /docs/directory ("Directory & Inventory") - help icon on the Directory page header links to it (same pattern as users/groups/profile pages) - linked from the docs site index feature list - extended with the shared slug conventions (site_, host_), the automatic registration story (theta-env stack seeding, ldap-client Linux host enrollment), and the admin + read-only API surface (the read-only graph routes live at /api/discovery, not /api/directory). Co-Authored-By: Claude Opus 4.8 --- docs/directory.md | 38 ++++++++++++++++++++++++++++++++++++++ docs/index.md | 1 + nodejs/routes/docs.js | 1 + nodejs/views/directory.ejs | 1 + 4 files changed, 41 insertions(+) diff --git a/docs/directory.md b/docs/directory.md index 353ef9b..92f230f 100644 --- a/docs/directory.md +++ b/docs/directory.md @@ -57,3 +57,41 @@ Resources carry a flexible `metadata` JSON object that can store essential conte ## Navigating the UI The Directory Management interface provides a **Tree View** toggle that visually nests your resources, making it easy to comprehend your network topography at a glance. You can also filter, search, and sort your entire infrastructure inventory. From the tree view, you can click the green `+` icon next to any resource to instantly add a child resource beneath it. + +## Slug conventions + +Slugs are the stable identifiers automation keys off, so the tooling around the SSO Manager follows a shared convention: + +- **Sites**: `site_` — e.g. `site_local`, `site_us-east` +- **Hosts**: `host_` — e.g. `host_pve1`, `host_web01` +- **Services/apps**: a plain slug or `app_` — e.g. `sso-manager`, `app_emby` + +The auto-created LDAP groups derive from the slug (`_access` / `_admin`), so keep slugs stable once access groups are in use. + +## Automatic registration + +You don't have to build the graph by hand — the theta42 tooling registers itself: + +### The stack itself (theta-env) + +[theta-env](https://github.com/theta42/theta-env)'s `./setup.sh` seeds the directory on every run with the stack it deploys: + +- a **site** (name from `CFG_SITE_NAME` in `setup.env`, default `local` → slug `site_local`) marked as the current site +- the **host** the stack runs on (`host_`), with IP, MAC address, OS, and kernel collected from the machine +- the **services** it composes — SSO Manager, Proxy (management UI), OpenLDAP Directory (the LDAPS endpoint Linux hosts and LDAP-native apps bind to), and OpenResty Edge (the 80/443 data plane) — each with its address, internal port, and git repo +- the proxy's auto-registered **OAuth client**, linked under its service + +The seed is idempotent and non-destructive: a resource whose slug already exists is considered operator-owned — the seed only fills in metadata fields you haven't set, and never overwrites your values. + +### Linux hosts (ldap-client) + +The `ldap-client` join script enrolls a Debian/Ubuntu machine for LDAP login (SSSD/PAM), LDAP-backed `sudo`, and SSH keys from the directory — and, when given an SSO API token, registers the machine as a `host_` resource with its IP, MAC, OS, and kernel, parented to the site named by its configured location. + +## API + +All of the above uses the same admin API the UI does (group `app_sso_directory_admin` or `app_sso_admin`): + +- `GET/POST /api/directory-admin/resources`, `PUT/DELETE /api/directory-admin/resources/:id` +- `GET/POST/DELETE /api/directory-admin/edges` — parent/child links (`hosts`, `oauth` relations) +- `GET/POST/DELETE /api/directory-admin/groups` — resource ↔ LDAP group links +- Read-only graph views (any authenticated user): `GET /api/discovery/resources`, `/api/discovery/resources/:slug`, `/api/discovery/graph`, `/api/discovery/me` diff --git a/docs/index.md b/docs/index.md index ac495e0..b78bf01 100644 --- a/docs/index.md +++ b/docs/index.md @@ -58,6 +58,7 @@ backend, that's the niche. - **All-in-one Docker image** — app + OpenLDAP + Redis in one container, or run the pieces separately via `app_*` env config. - **Geo-Location Scaling** — built-in support for N-Way Multi-Master OpenLDAP [replication](replication.html) across physical sites. +- **[Directory & Inventory](directory.html)** — map sites, hosts, and services as a graph with rich metadata (IP/MAC, OS/kernel, ports, git repos), auto-provisioned access groups, and automatic registration from theta-env and ldap-client. ## Get it diff --git a/nodejs/routes/docs.js b/nodejs/routes/docs.js index 1c6ef1b..564181f 100644 --- a/nodejs/routes/docs.js +++ b/nodejs/routes/docs.js @@ -33,6 +33,7 @@ const DOCS = { accounts: {title: 'Accounts, Groups & Managers', file: path.join(__dirname, '../../docs/concepts-accounts.md')}, 'oauth-apps': {title: 'Connecting Apps (SSO)', file: path.join(__dirname, '../../docs/concepts-oauth-apps.md')}, 'api-tokens': {title: 'API Tokens', file: path.join(__dirname, '../../docs/concepts-api-tokens.md')}, + directory: {title: 'Directory & Inventory', file: path.join(__dirname, '../../docs/directory.md')}, overview: {title: 'Overview', file: path.join(__dirname, '../../README.md')}, changelog: {title: 'Changelog', file: path.join(__dirname, '../../CHANGELOG.md')}, diff --git a/nodejs/views/directory.ejs b/nodejs/views/directory.ejs index 9a4a95d..955cef6 100644 --- a/nodejs/views/directory.ejs +++ b/nodejs/views/directory.ejs @@ -29,6 +29,7 @@
Manage infrastructure, services, and their relationships. +