Files

T

wmantly 9fb240ff45 theta-env: unified SSO Manager + Proxy stack with one-command setup

Composes theta42/sso-manager-node and theta42/proxy (as git submodules) on a
single Docker network and automates first-run wiring.

- docker-compose.yml: sso-manager (build ./sso-manager-node/Dockerfile.openldap)
  + proxy (build ./proxy/Dockerfile) on theta-net; SSO UI + mgmt port bound to
  localhost, LDAPS published, proxy 80/443/4443 published.
- setup.sh: idempotent one-command bring-up — validates .env, starts SSO, runs
  the bootstrap, writes ./proxy.env, starts the proxy, prints admin login.
- bootstrap/bootstrap.js: runs inside the sso-manager container (self-contained,
  Node built-ins + fetch only) — creates the LDAP service account, first admin
  (+ app_sso_admin/app_sso_oauth_admin membership), registers the proxy as an
  OIDC client via the SSO HTTP API, emits CLIENT_ID/CLIENT_SECRET.
- .env.example: all tunables (LDAP_BASE_DN, LDAP_ADMIN_PASS, JWT_SECRET,
  SSO_HOST, PROXY_HOST, BOOTSTRAP_ADMIN_*, LDAP_SERVICE_PASS, SMTP_*, ports).
- README.md + docs/ (Jekyll site for GitHub Pages): quickstart, architecture,
  standalone usage.

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

2026-07-11 17:04:36 -04:00

4.5 KiB

Raw Blame History

layout, title

layout	title
default	Quickstart

Quickstart Guide

← Back to Home

Prerequisites

A Linux host with Docker + Docker Compose (the v2 plugin docker compose or the v1 standalone docker-compose both work).
Two hostnames that resolve to the host: one for the SSO UI (SSO_HOST), one for the proxy mgmt UI (PROXY_HOST). On a real network add DNS records; for a local try, add them to /etc/hosts.
Port 80 + 443 reachable from the internet if you want Let's Encrypt certs; otherwise the proxy serves a self-signed fallback (browsers warn — expected for LAN use).

1. Clone

git clone --recursive https://github.com/theta42/theta-env.git
cd theta-env

--recursive fetches the two submodules (sso-manager-node, proxy) in one step. If you forgot it:

git submodule update --init --recursive

2. Configure `.env`

cp .env.example .env

Edit .env. The required values:

Key	Example	Notes
`LDAP_BASE_DN`	`dc=lab,dc=local`	your directory base
`LDAP_ADMIN_PASS`	`...`	LDAP root password — save it
`JWT_SECRET`	(blank)	leave blank to auto-generate + persist — save it
`SSO_HOST`	`sso.lab.local`	hostname the proxy serves the SSO UI at
`PROXY_HOST`	`proxy.lab.local`	hostname the proxy serves its own UI at
`BOOTSTRAP_ADMIN_UID`	`admin`	your first admin login
`BOOTSTRAP_ADMIN_PASS`	`...`	first admin password

Optional: BOOTSTRAP_ADMIN_EMAIL, LDAP_SERVICE_PASS (auto-generated if blank), SMTP_* (for SSO password-reset/invite emails), LDAP_CERT_CN, and host port overrides (SSO_PORT, LDAPS_PORT, HTTP_PORT, HTTPS_PORT, HTTPS_ALT_PORT, MGMT_PORT). See .env.example for the full commented list.

3. Run

./setup.sh

What happens:

Validates .env (copies from .env.example if missing, then exits so you can edit it).
Builds + starts sso-manager, waits for /health.
Runs the bootstrap inside the sso-manager container — creates the LDAP service account, your first admin, and the proxy's OAuth client, and prints the client id + secret.
Writes ./proxy.env (the proxy's app_* config) from .env + the bootstrap output.
Builds + starts proxy, waits for /health.
Prints your first-admin login + the public URLs.

The first run builds two Docker images (a few minutes). Subsequent runs are fast.

4. Point DNS at the host

SSO_HOST and PROXY_HOST must resolve to the host running the stack. Add DNS records, or for a local try:

echo "127.0.0.1 sso.lab.local proxy.lab.local" | sudo tee -a /etc/hosts

(The proxy needs port 80 reachable for Let's Encrypt; on a LAN without that it serves a self-signed cert — browsers will warn, which is fine for home-lab use.)

5. Log in

Open https://<SSO_HOST> and log in as your bootstrap admin (BOOTSTRAP_ADMIN_UID / BOOTSTRAP_ADMIN_PASS). From there you can add users, groups, and OAuth clients.

The proxy mgmt UI is at https://<PROXY_HOST> (same admin SSO login protects it). Add the Host records you want to protect with OIDC.

First-run fallbacks (if DNS/TLS isn't ready yet): SSO UI at http://127.0.0.1:3001, proxy UI at http://127.0.0.1:3000.

Re-running

./setup.sh is idempotent — safe to re-run after editing .env, after a docker compose down, or after restoring from backup. It converges the stack to your .env values (LDAP service account + admin passwords are reset to .env; the OAuth client is left alone if proxy.env exists).

Direct LDAP for legacy apps

Legacy apps bind LDAP directly over LDAPS:

ldapsearch -x -H ldaps://<host>:636 \
  -D "cn=ldapclient,ou=people,dc=lab,dc=local" -W \
  -b "ou=people,dc=lab,dc=local" '(objectClass=posixAccount)' cn mail

Use the cn=ldapclient service account (read-only, the bootstrap created it) or the admin DN. Use LDAPS (636), not plain LDAP.

Backups

docker compose exec sso-manager slapcat -f /etc/openldap/slapd.conf \
  -b "$LDAP_BASE_DN" > backup-$(date +%F).ldif

Keep .env + proxy.env alongside it. Restore is ldapadd/ldapmodify into a fresh directory, then re-run ./setup.sh.

Next steps

Add users / groups in the SSO UI.
Add Host records in the proxy UI to protect your apps with OIDC.
See Architecture for how it all fits together, and Standalone to run either project on its own.