Skip to content

Deployment

Infrastructure Overview

The system consists of a single CDK stack (AllDocsStack) that deploys three main infrastructure components:

  1. Webhook Handler Lambda - Receives GitHub webhook events and triggers rebuilds
  2. Docs Rebuilder Lambda - Runs the full rebuild pipeline (aggregate → build → deploy to S3)
  3. S3 Bucket + CloudFront - Static website hosting with Okta authentication

Important: We always deploy the entire stack together. There is no way to deploy individual components.

Prerequisites

Deployment requires:

  • AWS Access: You must have access to the platformsso-stage-836194 AWS account (ID: 022311445169)
  • AWS CLI: Configured with appropriate credentials
  • Node.js & pnpm: To build TypeScript packages
  • Python: For custom MkDocs plugins

If you don't have access, contact Axel Tetzlaff or someone from the UAS team.

Deployment Process

1. Build All Components

From the repository root:

pnpm build

This builds all TypeScript packages in the workspace: - aggregator - Compiles to aggregator/dist/ - webhook-handler - Compiles to webhook-handler/dist/ - cdk - Compiles CDK stack code

2. Deploy Infrastructure

pnpm deploy:infra

This command: 1. Runs pnpm build to ensure all TypeScript is compiled 2. Builds the Docker image for the docs-rebuilder Lambda (includes aggregator, MkDocs, handler) 3. Deploys the complete CDK stack to AWS

The deployment takes several minutes as it builds the Docker image and uploads to ECR.

See the Developer Guide for other available scripts.

Content Updates

Content is NOT deployed from your local machine. The S3 bucket gets populated exclusively by the docs-rebuilder Lambda, which can be triggered:

  • Automatically: Via GitHub webhooks when /docs folders are modified
  • Manually: By invoking the Lambda directly (see Monitoring)

This design prevents accidental deployment of incomplete local documentation.

Deployment Status

Deployments are not automated and must be executed manually by someone with AWS access. We deploy infrastructure changes as needed when updating Lambda functionality or CDK configuration.

Rollback

If a deployment causes issues:

  1. Revert the code changes in git
  2. Run pnpm deploy:infra again with the reverted code
  3. CDK will update the stack to the previous state

Note: S3 content is not affected by infrastructure rollbacks—content only changes when the rebuilder Lambda runs.

Last updated: March 31, 2026 at 11:02
By: Axel Tetzlaff