Hosting with Active Directory login

The documentation site is static HTML (Astro build). Active Directory login is handled by a small Node.js server in server/ that serves dist/ only after a successful AD bind — the same approach as HomeOwnerPortal-Node-2026/server/src/utils/ldap.js.

Two ways to run locally

Command	Auth	Use when
npm run dev	None	Writing or editing docs (Astro hot reload)
npm run start	AD (or dev bypass)	How you run the site for staff — build + protected server

npm run start runs npm run build, then node server/src/index.js.

First-time server setup

cd /path/to/sdc-docs
npm install
npm run server:install
cp server/.env.example server/.env
# Edit server/.env — set LDAP_SERVER and SESSION_SECRET
npm run start

Open http://127.0.0.1:4321/ — you will be redirected to Sign in unless already authenticated.

Environment variables

Copy server/.env.example to server/.env:

Variable	Required	Description
LDAP_SERVER	Yes (prod)	AD domain controller hostname, e.g. dc01.thesmartbuilder.local
LDAP_PORT	No	Default 389 (use 636 with LDAP_USE_TLS=true)
LDAP_URL	No	Full URL override, e.g. ldaps://dc01.example:636
SESSION_SECRET	Yes (prod)	Random string — openssl rand -hex 64
PORT	No	Default 4321
NODE_ENV	No	Set production when deployed
AUTH_DISABLED	No	true only for local dev without AD — never in production

Use the same LDAP_SERVER values as the Home Owner Portal Node server (HomeOwnerPortal-Node-2026/server/.env).

Who can sign in

• Accounts with a @smithdouglas.com UPN (or username without @ — the server appends @smithdouglas.com).
• Password is validated with an LDAP bind using that UPN (same as Workplace / SMART).

Homeowner WebUser table login is not used for this site.

Sign out

Use Sign out in the top bar (visible only when the auth server is in use), or POST /api/auth/logout.

Offline zip (Caddy) vs AD

package-local.ps1 still packages Caddy + static files with no login — useful for quick offline copies on a laptop.

For AD-protected hosting on a shared server:

1. npm run build
2. Run node server/src/index.js (or a process manager) on the host that can reach your domain controllers.
3. Put HTTPS in front (IIS ARR, reverse proxy, etc.) and set TRUST_PROXY=1 if needed.

Troubleshooting

Symptom	Check
Active Directory is not configured	LDAP_SERVER in server/.env
Invalid credentials	UPN format, password, VPN, firewall to DC
Redirect loop	SESSION_SECRET set; cookies allowed; HTTPS secure cookie in prod
dist/ not found	Run npm run build first

Health check (no auth): GET /api/health