docs: fix quickstart drift, add LICENSE, document admin bypass and LDAPS cert mount for public release
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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user