Skip to content

CDK Infrastructure

Purpose

The CDK stack (AllDocsStack) defines and deploys all AWS infrastructure for the documentation site. It's a single stack that manages the static website hosting, both Lambda functions, API Gateway, and all necessary permissions and integrations.

How It Works

The stack creates and wires together all infrastructure components:

  1. Static Website - Uses the StaticWebsite construct from @pit-shared/cdk to create S3 bucket, CloudFront distribution, SSL certificate, and Okta authentication
  2. Webhook Handler Lambda - Node.js function that receives GitHub webhooks via API Gateway
  3. Docs Rebuilder Lambda - Docker container Lambda that runs the full rebuild pipeline
  4. API Gateway - Exposes webhook endpoint for GitHub to call
  5. Permissions - Grants Lambdas access to Secrets Manager, S3, CloudFront, and each other

Key Resources

StaticWebsite (from @pit-shared/cdk)

  • S3 Bucket - Hosts static site files
  • CloudFront Distribution - CDN with Okta authentication
  • Route53 Record - DNS alias for docs.stage.sso.statista.com
  • Certificate - SSL/TLS certificate for HTTPS

Webhook Infrastructure

  • API Gateway - REST API with /webhook POST endpoint
  • Webhook Handler Lambda - Validates signatures, filters events, triggers rebuilder
  • DataDog Integration - APM instrumentation for the webhook handler

Rebuilder Infrastructure

  • Docker Lambda Function - Packages Node.js, Python, Git, aggregator, and MkDocs
  • IAM Permissions - Access to S3 (read/write), CloudFront (invalidation), Secrets Manager
  • Environment Variables - Bucket name, distribution ID, secret name

Shared Resources

  • Secrets Manager Reference - Points to docs-builder/github-app secret (GitHub App credentials, webhook secret, DataDog API key)

Stack Outputs

The stack exports useful values:

  • WebsiteURL - The documentation site URL
  • DistributionId - CloudFront distribution ID (for manual cache invalidation)
  • WebhookURL - GitHub webhook endpoint URL
  • DocsRebuilderFunctionName - Lambda function name (for manual invocation)

Region

All resources are deployed to us-east-1 (required by the StaticWebsite construct for CloudFront edge lambdas).

Deployment

pnpm deploy:infra

This builds all TypeScript components, builds the Docker image, and deploys the complete stack.

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