Skip to content
This repository was archived by the owner on May 20, 2026. It is now read-only.

README.md

Latest commit

 

History

History
293 lines (207 loc) · 8.36 KB

README.md

File metadata and controls

293 lines (207 loc) · 8.36 KB

DO NOT USE

This repo is superceded by our app kit see: https://github.com/co-cddo/gds-idea-app-kit

Web App Template with AWS Cognito Authentication

A template repository for deploying Streamlit, Dash, or FastAPI applications easily within the gds-idea infrastructure.

Features

  • 🚀 Multi-framework support: Choose between Streamlit, Dash, or FastAPI
  • 🔐 Built-in authentication: GDS-IDEA team cognito
  • 🛠️ Dev container ready: VS Code dev containers for instant development environment
  • ✅ Smoke testing: Validate builds and health checks before deployment

Quick Start

Prerequisites

If you need to install any of the above it is recommended to use brew

1. Clone and Install

git clone <this-repo>
cd <repo-name>
uv sync

2. Configure Your App

Choose your app name and framework:

# Set app name and framework (streamlit, dash, or fastapi)
uv run configure my-app streamlit

# This updates pyproject.toml and copies framework files to app_src/

Or edit pyproject.toml manually:

[tool.webapp]
app_name = "my-app"
framework = "streamlit"  # or "dash" or "fastapi"

Then sync:

uv run configure

3. Develop

Option A: VS Code Dev Container (Recommended)

  1. Open in VS Code
  2. Click "Reopen in Container" when prompted
  3. Dependencies auto-install, dev environment ready
  4. Run your app inside the container

Option B: Smoke Test

# Build and test with Docker
uv run smoke_test --wait

# Then open http://localhost:8501

4. Deploy to AWS

# Set AWS environment - you should have this configured already.
export AWS_PROFILE=you-dev-profile

# Deploy
cdk deploy

Project Structure

.
├── app.py                      # CDK infrastructure definition - modify this
├── pyproject.toml              # Project config (includes [tool.webapp])
├── cdk.json                    # CDK configuration
│
├── template/                   # Template tooling (DO NOT edit manually)
│   ├── configure.py            # Configuration script
│   ├── smoke_test.py           # Docker smoke test
│   ├── provide_role.py         # AWS credentials provider for dev container
│   └── frameworks/             # Framework templates
│       ├── streamlit/
│       ├── dash/
│       └── fastapi/
│
├── app_src/                    # Active application (generated) add your app here.
│   ├── Dockerfile              # This will be configured for your framework
│   ├── pyproject.toml          # Add app dependencies here, cd app_src then uv add
│   └── <framework>_app.py.     # Modify the template
│
├── .aws-dev/                   # AWS credentials for dev container (gitignored)
│   ├── credentials             # Generated by provide_role script
│   └── config                  # Generated by provide_role script
│
└── .devcontainer/              # VS Code dev container config
    └── docker-compose.yml

Available Commands

Template Configuration

# Configure with CLI arguments
uv run configure <app-name> <framework>

# Sync from pyproject.toml (after manual edit)
uv run configure

Testing

A utility to check the docker build as expected is included. It will build the container, start it up, ping the health check address and clean up. If this runs you can be confident when you deploy that it will work.

# Smoke test (quick validation)
uv run smoke_test

# Smoke test with interactive wait
uv run smoke_test --wait

Running with the --wait command delays shutting down and cleaning up the container until you hit a key. This allows you to access the app locally.

AWS Credentials for Dev Container

If your app needs AWS access during development, provide credentials to the dev container:

# Set your AWS profile (dev/prod role from GDS-users)
export AWS_PROFILE=aws-prototype

# Pass-through mode: Use your current profile credentials
uv run provide_role

# Role assumption mode: Assume container role (if configured in pyproject.toml)
uv run provide_role  # Uses aws_role_arn from [tool.webapp.dev]

# Force pass-through (skip role assumption)
uv run provide_role --use-profile

When to use each mode:

  • Pass-through: Early development, container role doesn't exist yet, testing with dev/prod permissions
  • Role assumption: Testing with production-like permissions, validating container role works

See .devcontainer/README.md for detailed setup including 8-hour credential configuration.

CDK Commands

# Synthesize CloudFormation template
cdk synth

# List stacks
cdk ls

# Compare with deployed stack
cdk diff

# Deploy
cdk deploy

# Destroy
cdk destroy

Architecture

The infrastructure uses custom CDK constructs from gds-idea-cdk-constructs.

Authentication

Authentication is handled centrally by the core infrastrcture. You turn it on in the webApp by running with AuthType.COGNITO.

Authorisation

Authorisation, who can access the app, is performed in app. Applications use the cognito-auth library which has examples for each of the frameworks. This template gives you a minimal app configured with cognito-auth.

When working locally you can mock the the authoriser and user for testing. See the dev_mocks folder, which is automatically mounted in your local container.

Development Workflow

  1. Configure: uv run configure my-app streamlit
  2. Develop: Open in VS Code dev container or run uv run smoke_test --wait
  3. Customize App: Edit app_src/<framework>_app.py
  4. Customize CDK: Edit app.py
  5. Test: run uv run smoke_test - validates build and health checks
  6. Deploy: cdk deploy to AWS
  7. Iterate: Switch frameworks anytime with uv run configure

AWS Authentication for Dev Container (Optional)

If your application needs AWS access during development (e.g., to access S3, DynamoDB, etc.), you can provide AWS credentials to the dev container.

Understanding the Two-Role Model

There are two different AWS roles in this project:

  1. Deployment Role - Your personal AWS role used to run cdk deploy (you already have this)
  2. Runtime Role - The role your application needs when running in the container (what provide_role sets up)

Setup

  1. Configure the runtime role in pyproject.toml:
[tool.webapp.dev]
aws_role_arn = "arn:aws:iam::123456789012:role/AppRuntimeRole" # get this from console or your CDK
aws_region = "eu-west-2"  # Optional, defaults to eu-west-2
  1. Provide credentials to the container (run on your HOST machine):
# Interactive - prompts for MFA code
uv run provide_role

# Non-interactive
uv run provide_role --mfa-code 123456

# Custom duration (1 hour instead of default 12 hours)
uv run provide_role --mfa-code 123456 --duration 3600
  1. Credentials are immediately available in the dev container (no restart needed!)
# Inside dev container
aws sts get-caller-identity
# Your app now has AWS access

How It Works

  • MFA device is auto-detected from your AWS configuration
  • Temporary credentials are written to .aws-dev/ on your host (gitignored)
  • This directory is mounted into the container at /home/vscode/.aws/
  • AWS SDK/CLI automatically uses these credentials
  • Credentials expire after 12 hours by default
  • To refresh: just re-run uv run provide_role on your host

Notes

  • ⚠️ This is optional - only needed if your app requires AWS access during development
  • ✅ Credentials update live - no container restart needed
  • ✅ Completely separate from CDK deployment credentials
  • ✅ Standard AWS credentials format ([default] profile)

Switching Frameworks

# Switch to FastAPI
uv run configure my-app fastapi

# Or edit pyproject.toml and sync
uv run configure

This updates the configuration and copies new framework files to app_src/.