Skip to content

11. Deploy this docs site

This documentation is a separate little website built with MkDocs (the Material theme). You publish it by building it into a plain folder and uploading that folder to Cloudflare Pages — no GitHub connection, no automation. Then you put it behind the same Microsoft 365 sign-in at docs.oncall.totlcom.com.

The whole project lives in the docs-site/ folder inside oncall-scheduler:

docs-site/
├── mkdocs.yml          # site settings (theme, navigation)
├── requirements.txt    # the Python packages needed to build
└── docs/               # all the pages you're reading, as Markdown

All in one command

cd "C:\LocalDev\On Call Scheduling\oncall-scheduler\docs-site"
mkdocs build
npx wrangler pages deploy site --project-name oncall-docs

Part 1 — Build the site into a folder

1a. Install Python (one-time)

MkDocs is a Python tool.

  1. Go to https://www.python.org/downloads/ and install Python 3.x (defaults are fine).
  2. On Windows, tick "Add Python to PATH" on the first installer screen.

  3. Confirm in a terminal:

    python --version

    (On macOS you may need python3 --version.)

1b. Install MkDocs Material (one-time)

In a terminal, go into the docs-site folder and install the packages:

cd "C:\LocalDev\On Call Scheduling\oncall-scheduler\docs-site"
pip install -r requirements.txt

(On macOS, use pip3 if pip isn't found.)

Re-run this after pulling changes

requirements.txt gains packages over time — the clickable-screenshot lightbox (mkdocs-glightbox) was added this way. If mkdocs build fails with "The 'glightbox' plugin is not installed", you're on an older set of packages: run the pip install -r requirements.txt above again.

1b-2. Generate the screenshots (one-time, and after UI changes)

The user guide embeds screenshots that are generated, not committed by hand. If the images are missing, run this from the repo root (not docs-site):

npm run db:migrate:local   # only if you've never set up the local database
npm run docs:shots

It builds the app, serves it locally, drives it with Playwright and writes 17 PNGs into docs-site/docs/assets/img/. See that folder's README.md for detail.

Local only

The generator writes to the database — it generates a year, books PTO and ignores an issue so the screens aren't empty. Never point it at production.

1c. Preview it locally (optional but nice)

mkdocs serve

Open http://127.0.0.1:8000 to see the docs with live reload while you edit. Press Ctrl+C to stop.

1d. Build the folder you'll upload

mkdocs build

This creates a site/ folder inside docs-site/ containing the finished website (plain HTML/CSS/JS). That site/ folder is the thing you copy-paste to Cloudflare.

Rebuild whenever the docs change

Any time you edit a page under docs-site/docs/, run mkdocs build again to refresh the site/ folder, then re-upload (Part 2).

Part 2 — Upload the folder to Cloudflare Pages

This uses Cloudflare's Direct Upload (drag-and-drop) — no GitHub.

  1. In the Cloudflare dashboard: Workers & Pages → Create application → Pages → Upload assets.
  2. Project name: oncall-docs (this becomes a temporary oncall-docs.pages.dev URL).

  3. Drag the contents of the site/ folder onto the upload area — or zip the site folder and drop the zip.

    Upload the contents, not nested

    The index.html must end up at the top level of the upload. If you accidentally upload the site folder itself, the site lands one level too deep and shows "Not Found." Open the site folder, select everything inside it, and upload that.

    1. Click Deploy site. You'll get https://oncall-docs.pages.dev.

Updating later

When the docs change: run mkdocs build again, then in the oncall-docs Pages project click Create deployment (or Upload) and drop the new site/ contents. Each upload is a new version you can roll back to.

Prefer the command line?

You can also upload with Wrangler instead of drag-and-drop:

npx wrangler pages deploy site --project-name oncall-docs

Same result — pick whichever you find easier.

Part 3 — Custom domain docs.oncall.totlcom.com

  1. Open the oncall-docs Pages project → Custom domains → Set up a custom domain.
  2. Enter docs.oncall.totlcom.com and confirm. Since totlcom.com is on Cloudflare, accept the DNS record it offers.
  3. Wait for the domain to show Active (HTTPS is automatic).

Part 4 — Put the docs behind Microsoft 365 too

You already set up Cloudflare Access for the main app (step 9). Add a second Access application for the docs so only staff can read them.

  1. Zero Trust → Access → Applications → Add an application → Self-hosted.
  2. Application name: On-Call Docs.
  3. Application domain: subdomain docs.oncall, domain totlcom.com (full: docs.oncall.totlcom.com).
  4. Identity providers: enable Microsoft 365 (the provider you created in step 9 — you don't need to recreate it).
  5. Next, then add a policy:
    • Name: TOTLCOM staff
    • Action: Allow
    • Include: Emails ending in @totlcom.com (or the same group/list you used for the app).
  6. Add application.

Reuse, don't recreate

The Microsoft identity provider from step 9 is shared across all your Access applications. For the docs you only add a new application + policy, pointing at the docs domain.

Confirm

Open https://docs.oncall.totlcom.com in a private window — you should be sent to Microsoft sign-in, then see these docs.

Troubleshooting