theta-suite/docs/index.md

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.

Quick start

git clone --recursive https://github.com/theta42/theta-env.git
cd theta-env
./setup.sh        # generates ./config/ the first time — edit it, then re-run
./setup.sh        # builds + bootstraps + starts the stack

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

• GitHub Repository
• Issue Tracker

License

MIT License — see the repository for details.