Deploy this docs site¶

This documentation is a small separate website built with MkDocs (Material theme). It lives in the docs-site/ folder of the repo. You build it into a plain folder and upload that folder to Cloudflare Pages, then put it behind the same Microsoft 365 sign-in at docs.drives.totlcom.com. The app's top bar (book icon, and links in ?) points there.

All in one command (after the one-time setup below)¶

cd C:\DevLocal\Drive-Destruction-Tracking
npm run docs:deploy

Part 1: Build the site¶

1a. Install Python (one time)¶

Go to https://www.python.org/downloads/ and install Python 3.
On the first installer screen, tick "Add Python to PATH".
Check it in PowerShell:
```
python --version
```

1b. Install MkDocs (one time, and again when `requirements.txt` changes)¶

cd C:\DevLocal\Drive-Destruction-Tracking
pip install -r docs-site\requirements.txt

1c. Preview (optional)¶

npm run docs:serve

Open http://127.0.0.1:8000. Pages reload as you edit. Press Ctrl+C to stop.

1d. Screenshots (after UI changes)¶

The screenshots use made-up demo data on your local database, never real customers.

npm run db:migrate:local    # only if you've never set up the local database
npm run docs:seed           # adds the demo customers and drives (local only)
npm run dev                 # leave this window running

In a second PowerShell window:

npm run docs:shots

It writes the PNGs into docs-site\docs\assets\img\.

Local only

docs:seed writes demo records to your local database. Never run it with --remote.

Part 2: Create the Pages project (one time)¶

npx wrangler pages project create drive-docs --production-branch main

Then deploy:

npm run docs:deploy

It prints a temporary address like https://drive-docs.pages.dev.

Part 3: Custom domain `docs.drives.totlcom.com`¶

Cloudflare → Workers & Pages → drive-docs → Custom domains → Set up a custom domain.
Enter docs.drives.totlcom.com and accept the DNS record it offers.
Wait until it shows Active.

Part 4: Put the docs behind Microsoft 365¶

Zero Trust → Access → Applications → Add an application → Self-hosted.
Application name: Drive Tracker Docs.
Application domain: docs.drives.totlcom.com. Add a second domain drive-docs.pages.dev (and *.drive-docs.pages.dev) so the temporary addresses are protected too.
Identity providers: the existing Microsoft 365 provider.
Policy: Name TOTLCOM staff, Action Allow, Include Emails ending in @totlcom.com.
Add application.

Reuse, don't recreate

The Microsoft identity provider is shared with the app's Access application. You only add a new application and policy.

Check it¶

Open https://docs.drives.totlcom.com in a private window: you should be sent to Microsoft sign-in, then see these docs. In the app, the book icon in the top bar opens the same page.

Updating later¶

Edit a page under docs-site\docs\ (or a runbook under docs\: the Runbooks section includes them), then npm run docs:deploy. Each deploy is a new version you can roll back to under drive-docs → Deployments.