Files

T

wmantly b43c3d0d1d docs: fix quickstart drift, add LICENSE, document admin bypass and LDAPS cert mount for public release (#17 )

Cleanup pass ahead of the public release announcement:

- docs/index.md: fix the Quick Start block, which described a stale
  "edit config then re-run setup.sh a second time" flow. setup.sh now
  requires setup.env (with CFG_BASE_DN) before it will do anything, and
  builds + bootstraps + starts in a single run. Updated to match
  README.md's correct 4-line sequence.
- Add a standard MIT LICENSE at the repo root (theta42, 2026) so
  docs/index.md's "MIT License — see the repository for details" claim
  is actually true.
- docs/standalone.md: document the hardcoded auth.adminUsers:
  ['proxyadmin2'] local anti-lockout admin bypass written into every
  generated proxy-secrets.js — what it's for, that it requires a
  matching SSO user to actually use, and how to rename/extend/disable
  it.
- README.md + docker-compose.yml: fix the LDAPS strict-trust security
  note, which implied mounting the SSO's cert into the proxy was a
  config-only change. It also requires a docker-compose.yml edit
  (ldap-certs isn't mounted into the proxy service); added commented-out
  boilerplate for that mount and clarified the doc text.
- Also includes the pre-existing "Why use this instead of running the
  two separately?" README paragraph that was already staged as
  in-progress work.
- Verified: no Vagrant references, no emoji, and no hardcoded
  custom-domain URLs anywhere in this repo outside the proxy/ and
  sso-manager-node/ submodules; no docs/CNAME (github.io URL scheme
  confirmed).
- Added --- section dividers to docs/*.md to match README.md's
  formatting convention.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

2026-07-13 23:10:55 -04:00

5.0 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.

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_BASE_DN 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.0 KiB Raw Blame History