Skip to content

Deploy jhcloudops.com Runbook Site

System: (Active) JH CloudOps Runbook Site
Last updated: 2025-11-30

This runbook describes how to deploy or update the MkDocs + Material documentation site hosted at https://jhcloudops.com, using:

  • MkDocs (static site generator)
  • AWS S3 (static file storage)
  • AWS CloudFront (CDN)
  • Terraform (infrastructure as code)
  • AWS CLI (deployment to S3 + cache invalidation)

Preconditions

You should have:

  • Deployment-only AWS profile with least-privilege permissions.

Repo structure

jhcloudops-runbook/
  docs/
  mkdocs.yml
  infra/
    main.tf
    providers.tf
    foundation/
    runbook_site/

Terraform infra already applied

From ./infra you have run:

terraform init
terraform apply

This should have created:

  • S3 bucket for the site
  • CloudFront distribution
  • Route 53 aliases
  • ACM cert

AWS credentials

aws sts get-caller-identity succeeds, using the correct profile

MkDocs installed

From the repo root:

python3 -m venv .venv
source .venv/bin/activate
pip install mkdocs-material

Standard deployment procedure

1. Update doc content

From the repo root:

  • Edit Markdown files under docs/ as needed.
  • Ensure nav in mkdocs.yml is valid and there are no broken references.

Run local preview:

source .venv/bin/activate        # if not already active
mkdocs serve
  • Pages load
  • Nav works

2. Build the static site

From the repo root:

mkdocs build

This generates a site/ directory with static HTML/CSS/JS:

site/
  index.html
  systems/
    index.html
  runbooks/
    ...
  patterns/
    ...
  • Mkdocs builds successfully

3. Sync static files to S3

Safety checks:

  • Use dryrun aws s3 sync --dryrun before running the real sync
  • Verify S3 bucket is not publicly listable/readable

From the repo root

aws s3 sync site/ s3:// <bucket-name> --delete --profile  <profile-name>
  • --delete removes files from S3 that no longer exist locally.

4. Invalidate CloudFront cache

From the repo root

aws cloudfront create-invalidation  --profile <profile-name> \
  --distribution-id <distrobution-id> \
  --paths "/*"
  • CloudFront fetch fresh content from S3
  • Invalidation may take a few minutes to complete

5. Verification

After syncing and invalidating, open and check:

Open & confirm:

  • https://jhcloudops.com/
  • https://jhcloudops.com/systems/index.html
  • New or updated content is visible.

Optional: verify CloudFront status

  • AWS CloudFront console → select the distribution → Invalidations tab → check the latest invalidation status is Completed.

Future improvements

  • Add a Github Action workflow to automate:
    • mkdocs build
    • aws s3 sync
    • CloudFront invalidation
    • Version docs