gds-idea-app-kit

CLI tool for scaffolding and maintaining GDS IDEA web apps on AWS.

Generates projects with:

• Streamlit, Dash, or FastAPI framework
• AWS CDK infrastructure (ECS Fargate behind ALB with Cognito auth)
• VS Code dev container for local development
• Production-ready multi-stage Dockerfile

Prerequisites

Install with Homebrew:

brew install uv node git docker docker-compose colima aws-cdk

idea-app init will check all prerequisites are installed before creating a project. If anything is missing, it will tell you what to install.

Installation

idea-app is installed as a global CLI tool, not as a per-project dependency. Install it via the GDS IDEA package index.

Recommended — using idea-tools (see the index page for one-time setup):

idea-tools install gds-idea-app-kit

Alternative — without idea-tools:

uv tool install gds-idea-app-kit --index gds-idea=https://co-cddo.github.io/gds-idea-pypi/simple/

To upgrade to the latest version:

idea-tools upgrade gds-idea-app-kit
# or without idea-tools:
uv tool upgrade gds-idea-app-kit

If you previously installed from a git URL, switch to the index:

idea-tools install gds-idea-app-kit --reinstall

Verify it's working:

idea-app --version

New project

Scaffold a new project with idea-app init:

idea-app init streamlit my-dashboard

This creates a directory gds-idea-app-my-dashboard/ containing:

• app.py -- CDK entry point
• cdk.json -- CDK configuration
• app_src/ -- your application code, Dockerfile, and dependencies
• .devcontainer/ -- VS Code dev container configuration
• dev_mocks/ -- mock auth data for local development
• .gitignore -- pre-configured for Python, CDK, and dev artifacts

The tool runs cdk init, uv init, copies template files, installs CDK dependencies, and makes an initial git commit. All of this happens automatically.

Options

idea-app init <framework> <app-name> [--python 3.13]

• framework: streamlit, dash, or fastapi
• app-name: short name for your app (lowercase, hyphens ok). The gds-idea-app- prefix is added automatically.
• --python: Python version for the project (default: 3.13)

After init

cd gds-idea-app-my-dashboard

# Create the GitHub repo (requires gh CLI):
gh repo create co-cddo/gds-idea-app-my-dashboard --private --source . --push

# Or add a remote manually:
git remote add origin git@github.com:co-cddo/gds-idea-app-my-dashboard.git
git push -u origin main

Then open the project in VS Code and reopen in the dev container when prompted.

Migrating an existing project

If you have a project created from the gds-idea-app-templates template repository, migrate it to idea-app:

cd gds-idea-app-my-existing-project
idea-app migrate

The command is interactive and will:

1. Read your existing [tool.webapp] configuration
2. Ask you to confirm before making changes
3. Build a manifest from your current tracked files
4. Remove old template/ directory, [project.scripts], and [build-system] sections
5. Offer to update your files to the latest templates (with a dry-run preview first)

Run this on a clean branch so you can review the changes:

git checkout -b migrate-to-idea-app
idea-app migrate
git diff
git add -A && git commit -m "Migrate to idea-app"

Updating template files

When idea-app is upgraded with new template changes (Dockerfile improvements, devcontainer updates, etc.), update your project:

cd gds-idea-app-my-dashboard
idea-app update

The update command manages files like the Dockerfile, devcontainer config, and docker-compose. It does not touch your application code, cdk.json, or pyproject.toml.

How updates work

Each tracked file is compared against the manifest hash from the last update:

File state	What happens
Unchanged since last update	Overwritten with the latest template
Locally modified	Skipped. A .new file is written alongside for you to review
Missing from project	Created

When files are skipped, you'll see instructions to compare and merge:

diff app_src/Dockerfile app_src/Dockerfile.new

Options

idea-app update [--dry-run] [--force]

• --dry-run: show what would change without writing anything
• --force: overwrite all files, including ones you've modified locally

Other commands

smoke-test

Build and health-check the production Docker image:

idea-app smoke-test              # build + health check
idea-app smoke-test --build-only # just build, skip health check
idea-app smoke-test --wait       # keep running after health check, press Enter to stop

provide-role

Provide AWS credentials to the dev container by assuming the configured IAM role:

idea-app provide-role                  # assume role from [tool.webapp.dev]
idea-app provide-role --use-profile    # pass through current AWS profile instead
idea-app provide-role --duration 7200  # session duration in seconds (default: 3600)

Configure the role ARN in your project's pyproject.toml:

[tool.webapp.dev]
aws_role_arn = "arn:aws:iam::123456789012:role/your-dev-role"
aws_region = "eu-west-2"

Troubleshooting

docker compose not found / unknown shorthand flag -f

If docker compose version fails or you see unknown shorthand flag: 'f' in -f when running idea-app smoke-test, the Docker Compose plugin is not registered with the Docker CLI.

brew install docker-compose installs the binary but does not automatically register it as a Docker CLI plugin. You need to tell Docker where to find it.

Add the following to ~/.docker/config.json (create the file if it doesn't exist):

{
  "cliPluginsExtraDirs": [
    "/opt/homebrew/lib/docker/cli-plugins"
  ]
}

Then verify:

docker compose version

This should print something like Docker Compose version v2.x.x.

Development

# Clone and install dev dependencies
git clone git@github.com:co-cddo/gds-idea-app-kit.git
cd gds-idea-app-kit
uv sync

# Run unit tests
uv run pytest

# Run integration tests (requires CDK and network access)
uv run pytest -m integration

# Run all tests
uv run pytest -m ""

# Lint and format
uv run ruff check src/ tests/
uv run ruff format src/ tests/