Files

T

wmantly 7e679928ce Add Documentation link + screenshots to README and docs site

theta-env's GitHub Pages site (docs/, Jekyll) was already configured and
live at https://theta42.github.io/theta-env/ but nothing in the README
linked to it, unlike proxy and sso-manager-node's READMEs -- easy to miss
entirely. Add the same top-of-README Documentation link, plus screenshots
of the composed stack (SSO dashboard + proxy host list from one
./setup.sh run). Also fixes a stale docs/index.md quickstart snippet that
said "set CFG_BASE_DN to your domain" -- CFG_DOMAIN is the actual
required variable (CFG_BASE_DN is an advanced override); everywhere else
in the docs already says CFG_DOMAIN correctly.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-07-15 15:42:19 -04:00

5.3 KiB

Raw Blame History

layout, title

layout	title
default	Home

theta-env

A single repo that runs the whole theta42 identity + access stack — SSO Manager (OIDC provider + LDAP) and the theta42/proxy (OIDC-protected reverse proxy) — together, with one command, for home labs and small businesses.

It exists for people whose needs are met by these two projects and who want to run them "very simply." Each project still works standalone; this repo just wires them together and automates the first-run glue.

Screenshots

The SSO Manager and the proxy it fronts, both stood up by one ./setup.sh run:

SSO Manager Dashboard	Proxy Hosts

Quick start

git clone --recursive https://github.com/theta42/theta-env.git
cd theta-env
cp setup.env.example setup.env     # then edit setup.env: set CFG_DOMAIN to your domain
./setup.sh            # first run: generates ./config/ from setup.env, builds + bootstraps + starts

You need Docker + Docker Compose. ./setup.sh is idempotent — re-run any time to converge the stack to ./config/.

See the Quickstart Guide for a walkthrough of ./config/ and what setup.sh does, Architecture for how the pieces fit together, and Standalone for running each project on its own.

What you get

SSO Manager at https://<SSO_HOST> — log in as your first admin to manage users, groups, and OAuth clients. Fronted by the proxy under TLS.
Proxy at https://<PROXY_HOST> — add the Host records you want to protect with OIDC login.
LDAPS at ldaps://<host>:636 — legacy apps can bind directly (admin or the read-only cn=ldapclient service account the bootstrap creates).
API tokens — both apps let any logged-in user mint self-service personal access tokens (Authorization: Bearer sso_… / prx_…) to drive the management API from scripts/CI without a browser session. A token authenticates as its creator (carrying their permissions); mint/rotate/revoke under API Tokens in each UI. See each submodule's DEPLOYMENT for the details.

The `./config/` values you must set

All config and secrets live in ./config/sso-secrets.js + ./config/proxy-secrets.js (gitignored), generated by the first ./setup.sh. There is no .env. Set at least these in ./config/sso-secrets.js:

Key (in `sso-secrets.js`)	What it is
`stack.ldapBaseDn`	Directory base, e.g. `dc=lab,dc=local`.
`ldap.bindPassword`	LDAP root password (generated). Back it up.
`oauth.jwtSecret`	Signs the SSO's tokens (generated). Back it up.
`stack.ssoHost`	Public hostname the proxy serves the SSO UI at.
`stack.proxyHost`	Public hostname the proxy serves its own mgmt UI at.
`bootstrap.adminUid` / `bootstrap.adminPass`	Your first admin login.

See config.example/ for the full annotated shape (SMTP, LDAP cert CN, proxy OIDC/LDAP/auth, …).

Architecture

            ┌──────────────────────────────────────────────┐
            │  your browser / apps                          │
            └───────────────┬──────────────────────────────┘
                            │ https
                  ┌─────────▼─────────┐
                  │  proxy            │  OpenResty :80/:443/:4443
                  │  (OIDC + LDAP)    │  mgmt app :3000 (localhost)
                  └─────────┬─────────┘  bundled redis
              ┌─────────────┼──────────────────────┐
              │ ldaps:636   │ http:3001 (internal)│  OIDC token/userinfo
              ▼             ▼                      │
      ┌──────────────────────────┐                │
      │  sso-manager             │◄────────────────┘
      │  OIDC provider + OpenLDAP │  bundled redis
      │  web UI :3001 (localhost) │
      │  ldaps :636 (LAN clients) │
      └───────────────────────────┘

The proxy is both an OIDC client of the SSO (for login) and a direct LDAP client (for user lookups). See Architecture for the full diagram + the first-run bootstrap flow.

Documentation

Quickstart Guide — full walkthrough of ./config/ + setup.sh.
Architecture — the 3-repo + submodule + 2-container design, and how the bootstrap wires the proxy into a fresh SSO.
Standalone — running SSO Manager or the proxy on its own.

Community

License

MIT License — see the repository for details.

5.3 KiB Raw Blame History