Runbooks

Step-by-step operational procedures for provisioning and deploying infrastructure and applications.

Provision state backends

State backends are provisioned by CI using GitHub secrets. Local use is optional and requires backend.hcl files.

# Shared state backend
cd terraform/backend/shared
terraform init -backend-config=backend.hcl
terraform apply -var="subscription_id=<subscription-id>"

# Site state backend
cd terraform/backend/site
terraform init -backend-config=backend.hcl
terraform apply -var="subscription_id=<subscription-id>"

Warning

Only run backend provisioning if the storage accounts don't already exist. These are bootstrap-once resources.

Provision shared infrastructure

Shared infrastructure (PostgreSQL, RBAC) is managed through CI:

1. Make changes in terraform/envs/shared/
2. Create a PR against the release branch
3. CI runs terraform plan -- review the plan output
4. Merge the PR to trigger terraform apply

For local apply (not recommended):

cd terraform/envs/shared
terraform init -backend-config=backend.hcl
terraform apply \
  -var="subscription_id=<subscription-id>" \
  -var="server_name=<server-name>" \
  -var="admin_login=<admin-login>" \
  -var="admin_password=<admin-password>"

Provision site infrastructure

Same CI-driven workflow as shared infrastructure:

1. Make changes in terraform/envs/site/
2. PR to release → plan runs automatically
3. Merge → apply runs automatically

Deploy the portfolio site

1. Make changes in site/app/
2. Create a PR against release -- CI runs a build verification
3. Merge the PR -- CI builds and deploys to Azure Static Web Apps

Deploy the documentation hub

1. Make changes in hub/
2. Create a PR against release -- CI builds the hub for verification
3. Merge the PR -- CI builds and deploys to Azure Static Web Apps

Local site development

cd site/app
npm install
npm run dev

Local hub development

cd hub
pip install -r requirements.txt
mkdocs serve

The hub will be available at http://127.0.0.1:8000 with live reload.