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>
This commit is contained in:
2026-07-13 23:10:55 -04:00
committed by GitHub
parent 20a586de4f
commit b43c3d0d1d
7 changed files with 119 additions and 4 deletions
+20
View File
@@ -7,6 +7,8 @@ title: Quickstart
[← Back to Home](index.html)
---
## Prerequisites
- A Linux host with **Docker** + **Docker Compose** (the v2 plugin `docker
@@ -18,6 +20,8 @@ title: Quickstart
certs; otherwise the proxy serves a self-signed fallback (browsers warn —
expected for LAN use).
---
## 1. Clone
```bash
@@ -32,6 +36,8 @@ step. If you forgot it:
git submodule update --init --recursive
```
---
## 2. Configure `setup.env` (enter your domain once)
```bash
@@ -63,6 +69,8 @@ file shape.
> exist, `./setup.sh` migrates them into `./config/` preserving your existing
> secrets — no need to write a `setup.env`.
---
## 3. Run
```bash
@@ -86,6 +94,8 @@ What happens:
The first run builds two Docker images (a few minutes). Subsequent runs are
fast.
---
## 4. Point DNS at the host
`stack.ssoHost` and `stack.proxyHost` (from `./config/sso-secrets.js`) must
@@ -98,6 +108,8 @@ 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
@@ -110,6 +122,8 @@ 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 `./config/`, after
@@ -118,6 +132,8 @@ then converges the stack to your `./config/` values (LDAP service account + admi
passwords are reset to the config; the OAuth client is kept if `proxy-secrets.js`
already holds its creds).
---
## Direct LDAP for legacy apps
Legacy apps bind LDAP directly over LDAPS:
@@ -131,6 +147,8 @@ ldapsearch -x -H ldaps://<host>:636 \
Use the `cn=ldapclient` service account (read-only, the bootstrap created it)
or the admin DN. Use LDAPS (636), not plain LDAP.
---
## Backups and restore
`./setup.sh` auto-snapshots `./config/` + LDAP + both Redis to `./backups/<ts>/`
@@ -145,6 +163,8 @@ docker compose exec sso-manager slapcat -f /etc/openldap/slapd.conf \
-b "<base>" > backup-$(date +%F).ldif
```
---
## Next steps
- Add users / groups in the SSO UI.