Skip to content

Browsing & hosting the ISMS as a website

The ISMS is plain Markdown, so you can read it straight on GitHub. For a nicer, searchable experience — and to share a read-only site with an auditor — we render it with MkDocs Material.

Browse locally (1 minute)

pip install -r requirements-docs.txt     # once
python3 tools/site.py serve              # live site at http://127.0.0.1:8000

tools/site.py rebuilds the register/dashboard, stages the docs, and starts a local server with full-text search and navigation. Edit a document, save, and the page reloads. Stop with Ctrl-C.

To produce a static site (a site/ folder of HTML) for hosting:

python3 tools/site.py build              # outputs ./site

site/ and .sitesrc/ are git-ignored build artefacts — never commit them.

Host it behind a login (Cloudflare Pages + Access)

This gives you a private, authenticated site with zero servers to run. Free tier covers a small team and external auditors.

1. Deploy the site to Cloudflare Pages

  • Push this repo to GitHub (private).
  • In the Cloudflare dashboard → Workers & Pages → Create → Pages → Connect to Git, pick this repo.
  • Build settings:
  • Build command: pip install -r requirements-docs.txt && python3 tools/site.py build
  • Build output directory: site
  • Deploy. Cloudflare rebuilds the site on every push to main.

2. Put a login in front (Cloudflare Access / Zero Trust)

  • Cloudflare dashboard → Zero Trust → Access → Applications → Add application → Self-hosted.
  • Point it at your Pages domain (e.g. isms.soon.works or the *.pages.dev URL).
  • Add an Access policy: allow specific emails (your team) or your @soon.works domain; add the auditor's email when needed (you can time-box it).
  • Login method: one-time PIN by email, Google, or your IdP (Entra/Okta) — the same SSO Soon already uses.

Result: anyone visiting the site must authenticate; unauthorised users never reach it. Revoke the auditor's access in one click when the engagement ends.

Alternatives

  • GitHub Pages — simple, but only public or requires GitHub Enterprise for private access control. Cloudflare Access is the easier private option.
  • Netlify — equivalent to Pages; Soon already uses Netlify, so this is also fine (set the same build command/output dir, add Netlify password/Identity for login).

Keeping it current

The site is generated from the Markdown — there's nothing to maintain separately. Every push rebuilds it; REGISTER.md and STATUS.md are regenerated as part of the build so the live site always reflects the latest document statuses.