App installation guide on AWS with CDK

Installation with CDK

This guide explains how to install the app in AWS using the cdk/ folder in this repository. You need familiarity with AWS (console or CLI) and administrator access in at least one region.

Recommended: use the interactive installer script cdk/cdk_install.py, which writes config/cdk_config.env and cdk.json, validates your choices, and can run cdk deploy and post_cdk_build_quickstart.py for you. The sections below still document manual steps, deployment modes, and post-deploy tasks in full.

Quick start with `cdk_install.py`

The installer lives at cdk/cdk_install.py. From a terminal, cd into the cdk folder, activate a Python environment with CDK dependencies installed (pip install -r requirements.txt), ensure the AWS CLI and CDK CLI (npm install -g aws-cdk) are available, and sign in to AWS (for example aws sso login).

What the script does

Detects a Python interpreter with aws-cdk-lib and writes or updates cdk.json (with a timestamped backup of any existing file).
Optionally checks for existing RedactionStack / CloudFront / AppRegistry stacks and can delete them (--force-delete-stacks) before a clean install.
Runs a wizard (or accepts CLI flags) to collect profile, VPC/subnets, TLS, optional agentic redaction (second Gradio UI), orchestration backend (AgentCore, Pi, or LangGraph), headless batch, and add-on settings.
Writes config/cdk_config.env (backed up before overwrite), and when enabled:
- cdk/config/app_config.env — AWS deployment keys for the redaction app (merged from app_config.env.example);
- config/agent.env — agentic Gradio runtime settings (AGENT_ORCHESTRATOR, AGENTCORE_RUNTIME_URL, doc_redaction backend URL, and related keys). Legacy config/pi_agent.env is migrated automatically if present.
Validates incompatible combinations (for example Express Mode with an ACM certificate ARN, or headless batch with Express / agentic redaction / Service Connect).
Optionally bootstraps CDK, runs cdk synth, cdk deploy --all, post-deploy Cognito callback / secret fixups (API, no second deploy), and post_cdk_build_quickstart.py (CodeBuild image build + scale ECS Express services).

Run python check_resources.py before deploy when using existing VPC subnets, security groups, or imported resources; it writes precheck.context.json used at synth time. If you change CDK prefix or profile after a prior stack (for example headless → demo), re-run precheck so Cognito pools, secrets, and ECR repos are not incorrectly treated as “already exist” under an old name.

Use --config-only to generate config files without deploying; use --deploy-only to redeploy from an existing cdk_config.env.

Deployment profiles

The interactive wizard offers four base profiles. You can also pass --profile on the command line.

Profile	CLI	Typical use	Main defaults
Demonstration	`demo`	Pilots, sandboxes, agentic redaction on Express	ECS Express Mode, regional CloudFront with magic-link auth (`CLOUDFRONT_AUTH_MODE=magic-link`), public subnets, no delete protection, AppRegistry off (opt in via wizard)
Production	`production`	Browser HTTPS with your domain	Legacy Fargate + ACM certificate, CloudFront (Cognito on ALB), delete protection, AppRegistry off by default
Headless batch only	`headless`	S3-triggered jobs, no web UI	Legacy Fargate, `ENABLE_HEADLESS_DEPLOYMENT`, S3 batch Lambda, no Cognito hosted UI domain, no Express / agentic redaction
Custom	`custom`	Mixed settings	Wizard prompts for Express, CloudFront, delete protection, and AppRegistry individually

Headless batch add-on (not available on the Demonstration profile): enable on Production or Custom (with Express off) via the wizard, --headless, or --profile headless for a dedicated batch-only install. See Headless batch deployment below.

The wizard can list VPCs, subnets, and ACM certificates in your account when run interactively. Production mode requires an issued ACM certificate in your deployment region unless you choose Express (demo). Headless mode skips the Cognito hosted UI domain prompt entirely.

Common commands

Full interactive install (prompts for profile, VPC, deploy, quickstart):

cd cdk
python cdk_install.py

Demo sandbox — config only (no deploy):

python cdk_install.py --profile demo --config-only --yes

Production — partially non-interactive (existing VPC + ACM cert):

python cdk_install.py --profile production --vpc-name my-vpc \
  --cert-arn arn:aws:acm:eu-west-2:123456789012:certificate/abc-123 \
  --domain redaction.example.com --yes

Redeploy using existing config/cdk_config.env (skip quickstart):

python cdk_install.py --deploy-only --skip-quickstart

Headless batch only (S3 → Lambda → one-shot ECS direct mode, no always-on web UI):

python cdk_install.py --profile headless --vpc-name my-vpc --yes

Production with headless batch add-on (same stack also supports browser UI or batch — headless disables the always-on service; batch still works):

python cdk_install.py --profile production --headless --vpc-name my-vpc \
  --cert-arn arn:aws:acm:eu-west-2:123456789012:certificate/abc \
  --domain redaction.example.com --yes

Demo with agentic redaction on ECS Express (AgentCore orchestration is the default — CDK builds the runtime image, then creates the Bedrock runtime after CodeBuild):

python cdk_install.py --profile demo --enable-agentic --yes

AgentCore phase 2 only (after the AgentCore ECR image exists — no cdk deploy):

python cdk_install.py --complete-agentcore

Demo with Pi orchestration instead of AgentCore (Pi coding agent runs inside the agent Gradio container; Service Connect to main app):

python cdk_install.py --profile demo --enable-agentic --agent-orchestrator pi --yes

Production with agentic redaction on a dedicated hostname (legacy Fargate + Service Connect; Pi orchestrator by default on production):

python cdk_install.py --profile production --enable-agentic-legacy \
  --agentic-alb-routing host --agentic-host-header agent.example.com --yes

Clean reinstall (delete existing doc_redaction CloudFormation stacks first):

python cdk_install.py --profile demo --force-delete-stacks --yes

Other useful flags:

Flag	Purpose
`--synth-only`	Run `cdk synth` only
`--skip-deploy`	Stop after synth
`--skip-quickstart`	Skip `post_cdk_build_quickstart.py`
`--skip-cdk-json` / `--refresh-cdk-json`	Leave or rewrite `cdk.json`
`--skip-app-config-env`	Do not write `cdk/config/app_config.env`
`--skip-pi-agent-env`	Do not write `config/agent.env` (legacy flag name)
`--agent-orchestrator`	`agentcore` (demo default with `--enable-agentic`), `pi`, or `langgraph`
`--complete-agentcore`	AgentCore phase 2 only: create Bedrock runtime from ECR image
`--agentcore-runtime-url`	Pre-deployed AgentCore base URL (manual CLI deploy path)
`--public-subnet-mode` / `--private-subnet-mode`	`auto`, `existing`, or `create`
`--python`, `--region`, `--account`, `--cdk-prefix`, `--cognito-prefix`	Non-interactive identity

Run python cdk_install.py --help for agentic flags (--enable-agentic, --agentic-alb-routing, --agentic-path-prefix, --agentic-host-header, --enable-agentic-express, --enable-agentic-legacy, --agentcore-model, etc.). Older --enable-pi / --pi-* names remain as aliases.

After the installer finishes

Express (demo), no agentic redaction: wait for CodeBuild (~8 minutes in quickstart). With demo magic-link CloudFront, open RedactionLoginUrl from stack outputs once (sets a cookie), then browse via RedactionUrl / CloudFrontDistributionURL. Without magic-link, register a Cognito user if COGNITO_AUTH=True on the main app. The installer may patch Cognito callback URLs via API (no redeploy).
Express + agentic redaction (demo default: AgentCore): open AgentRedactionLoginUrl (magic-link demo) or sign in at AgenticExpressEndpoint (dedicated Express HTTPS URL). The main redaction backend runs with COGNITO_AUTH=False so the agent UI can call it (Service Connect for Pi/LangGraph; public HTTPS URL for AgentCore). Users authenticate on the agent UI only. If AgentCore phase 2 did not finish (ECR image still building), run python cdk_install.py --complete-agentcore after CodeBuild succeeds.
Production: point DNS at CloudFront or your ALB hostname; update Cognito callback URLs (see Additional Manual Tasks).
Headless batch: upload job .env files under the stack’s batch prefix on the output S3 bucket; no Cognito user or browser URL. Quickstart builds the image but does not start an always-on ECS service.
Application settings: edit repo config/config.env (OCR, Bedrock models, feature flags). For AWS resource names and COGNITO_AUTH, the installer also maintains cdk/config/app_config.env. On Express, redeploy with cdk deploy or re-run the installer after changing app_config.env so variables are inlined on the task; on legacy Fargate, app_config.env is uploaded to the logs S3 bucket at quickstart. Agent orchestration keys live in config/agent.env (uploaded by quickstart when agentic mode is on).
Service Connect / S3 batch / agentic redaction: see Optional deployment modes for constraints (several features require legacy Fargate, not Express).

If you prefer not to use the installer, continue with Prerequisites and Steps to install the app using CDK.

Prerequisites

Ensure you have an AWS Administrator account in your desired region to be able to deploy all the resources mentioned in cdk_stack.py.
Install git on your computer from: https://git-scm.com
Install nodejs and npm: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm. If using Windows, it may be easiest to install from the .msi installer at the bottom of the page here.
Install AWS CDK v2: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html
Ensure you have the latest version of the AWS CDK CLI installed: npm install -g aws-cdk

Bootstrap the environment with CDK in both your primary region, and us-east-1 if installing CloudFront and associated WAF.

# Bootstrap your primary region
cdk bootstrap aws://<YOUR_AWS_ACCOUNT>/eu-west-1

# Bootstrap the us-east-1 region
cdk bootstrap aws://<YOUR_AWS_ACCOUNT>/us-east-1

In command line, write:

git clone https://github.com/seanpedrick-case/doc_redaction.git

If you have previously installed the Redaction stack in the same AWS environment, many issues in re-installation using the following steps can be resolved by deleting the stack and starting again. Go to CloudFormation in the AWS console, and delete the stack (you may need to manually delete some components).

Note on ACM Certificates

To get full HTTPS data transfer through the app for browser users (CloudFront and/or Application Load Balancer with Cognito login), you need TLS termination backed by AWS Certificate Manager (ACM). There are two supported approaches in this CDK stack:

1. Your own ACM certificate (legacy Fargate path — recommended for production)
Set ACM_SSL_CERTIFICATE_ARN in config/cdk_config.env. You can request a certificate for your domain in ACM, or import an existing one. If you’re not sure, ask your IT admin. For a new domain certificate, validation often uses a CNAME; for HTTPS on a subdomain such as redaction.<domain-name>, include that name (or *.<domain-name>) on the certificate.

The stack then uses the legacy Fargate + ALB path: HTTPS on the load balancer, Cognito on the ALB, and (optionally) CloudFront in front. This keeps the full task definition (S3 config.env via environmentFiles, writable mount paths, Service Connect, S3 batch trigger, and so on).

After deploy, update DNS: include ACM validation CNAMEs as required, and point your app subdomain (e.g. redaction.<domain-name>) at the load balancer or CloudFront front URL.

2. AWS-managed ACM via ECS Express Mode (pilot/dev)
You can also get HTTPS without setting ACM_SSL_CERTIFICATE_ARN by enabling USE_ECS_EXPRESS_MODE=True. Express Mode provisions the load balancer and an AWS-managed ACM certificate for you (see stack output ExpressServiceEndpoint). That avoids obtaining and wiring your own certificate ARN, which can be useful for pilots or sandboxes.

Express still gives you HTTPS in the browser, but you have fewer options to change or extend the deployment later: the Express task model does not support S3 environmentFiles, many ephemeral volume mounts, readonlyRootFilesystem, Service Connect, or the S3 batch ECS trigger; app settings from config.env are inlined at CDK deploy time rather than loaded from S3 on the task. You cannot combine Express with ACM_SSL_CERTIFICATE_ARN in the same stack. If you expect to grow into production patterns (custom domain on your cert, batch jobs, Service Connect, full config from S3), start on the legacy + your own ACM certificate path rather than Express.

Details: ECS Express Mode below.

Optional deployment modes

The CDK stack supports additional opt-in modes configured in config/cdk_config.env. See cdk/cdk_config.py for all variables and inline comments. Example keys for agentic and AgentCore settings are in config/agent.env.example.

Mode	Main config flag	Best for
Legacy + ACM (default production)	`ACM_SSL_CERTIFICATE_ARN` set	Browser access, Cognito, CloudFront, full Fargate task
ECS Express Mode	`USE_ECS_EXPRESS_MODE=True`, no ACM ARN	Pilot/dev HTTPS without supplying your own certificate
Headless batch	`ENABLE_HEADLESS_DEPLOYMENT=True`	S3-uploaded job configs → Lambda → one-shot Fargate tasks (no web UI)
ECS Service Connect	`ENABLE_ECS_SERVICE_CONNECT=True`	Other ECS services in the same VPC calling the app API (legacy Fargate)
S3 batch ECS trigger	`ENABLE_S3_BATCH_ECS_TRIGGER=True`	Same as headless job path; can also be enabled on production without full headless
Agentic redaction on ECS (legacy)	`ENABLE_PI_AGENT_ECS_SERVICE=True`	Agent Gradio UI on shared manual ALB; Service Connect to main Fargate app
Agentic redaction on ECS Express	`ENABLE_PI_AGENT_EXPRESS_SERVICE=True`	Agent Gradio UI on its own Express HTTPS endpoint
Bedrock AgentCore runtime	`AGENTCORE_CDK_DEPLOY=True` + `ENABLE_AGENTCORE_RUNTIME=True`	Managed LangGraph runtime; Gradio proxies when `AGENT_ORCHESTRATOR=agentcore` (demo default)

Legacy ENABLE_ECS_SERVICE_CONNECT applies to the Fargate main service only. Express main + agentic Express use a cluster Cloud Map namespace and Service Connect applied in post_cdk_build_quickstart.py (not at initial cdk deploy). Headless and S3 batch require legacy Fargate (USE_ECS_EXPRESS_MODE=False). Do not enable legacy agentic (ENABLE_PI_AGENT_ECS_SERVICE) and Express agentic at the same time. Headless is incompatible with Express, agentic redaction, Service Connect, and CloudFront.

Agent orchestration (AGENT_ORCHESTRATOR in config/agent.env, set by the installer): agentcore (demo default with agentic Express — Gradio UI calls a Bedrock AgentCore runtime), pi (Pi coding agent with bash/skills inside the agent container), or langgraph (curated Python tools only, no shell). See Bedrock AgentCore runtime and agent-redact/agentcore/README.md.

ECS Express Mode (HTTPS without your own ACM certificate)

Amazon ECS Express Mode provisions a Fargate service, Application Load Balancer, and an AWS-managed ACM certificate from a single CDK resource. You get an HTTPS URL (stack output ExpressServiceEndpoint) without setting ACM_SSL_CERTIFICATE_ARN.

When to use: development, pilots, or environments where obtaining a customer ACM certificate is difficult. When not to use: production setups that rely on S3 environmentFiles, many ephemeral volume mount points, or readonlyRootFilesystem on the task—the Express container model does not support those; stay on the legacy path with your own ACM certificate.

Requirements:

USE_ECS_EXPRESS_MODE=True
Leave ACM_SSL_CERTIFICATE_ARN empty (CDK will error if both are set)
USE_ECS_EXPRESS_MODE cannot be used with ENABLE_ECS_SERVICE_CONNECT=True
Run CodeBuild and push an image to ECR before scaling the Express service (same as legacy)
aws-cdk-lib 2.230 or newer (see cdk/requirements.txt)

Application settings: At deploy time, CDK reads cdk/config/app_config.env and passes each variable as an inline container environment variable on the Express service (Cognito credentials still come from Secrets Manager). If you change app_config.env after deploy, run cdk deploy again to update the service. The quickstart script also uploads app_config.env to the logs S3 bucket for parity with the legacy path.

In-app Cognito (COGNITO_AUTH): Express demo with magic-link CloudFront (CLOUDFRONT_AUTH_MODE=magic-link) does not use in-app Cognito on the main app — unlock via RedactionLoginUrl / AgentRedactionLoginUrl stack outputs. Other Express setups may use in-app Gradio/Cognito login. When agentic Express is enabled, CDK sets COGNITO_AUTH=False on the main app so the agent UI can reach /doc_redact (Service Connect for Pi/LangGraph; public HTTPS for AgentCore). Users sign in on the agent URL instead. Optionally, keep main auth on and supply service-account credentials in agent.env via DOC_REDACTION_GRADIO_AUTH_USER / DOC_REDACTION_GRADIO_AUTH_PASSWORD (see config/agent.env.example).

Example cdk_config.env additions:

USE_ECS_EXPRESS_MODE=True
# ACM_SSL_CERTIFICATE_ARN=   # must be empty
USE_CLOUDFRONT=True          # optional; CloudFront can still front the Express-managed ALB
CLOUDFRONT_DOMAIN=d1234abcd.cloudfront.net

Cognito: With Express (or legacy ACM), set callback URLs to your CloudFront domain or Express endpoint, including https://<host>/oauth2/idpresponse when using ALB/Cognito login. After the first deploy without CloudFront, copy ExpressServiceEndpoint from CloudFormation outputs into ECS_EXPRESS_COGNITO_REDIRECT_BASE / COGNITO_REDIRECTION_URL if needed, then redeploy.

Do not enable Express on an existing production stack without a migration plan (risk of duplicate load balancers/services). Prefer a new stack or tear down the manual ALB/service first.

Agentic redaction on ECS Express (dedicated HTTPS URL)

Deploy the agent Gradio app (agent-redact/pi) as a second AWS::ECS::ExpressGatewayService on the same cluster. Each Express service gets its own AWS-managed HTTPS endpoint (stack outputs ExpressServiceEndpoint and AgenticExpressEndpoint).

Orchestration backends:

agentcore (demo default): the Gradio container proxies to a Bedrock AgentCore runtime (AGENTCORE_RUNTIME_URL). The runtime calls the main doc_redaction app over the public main Express / CloudFront URL (not Service Connect). CDK deploys the runtime image via CodeBuild (phase 1) and creates the Bedrock runtime after the image is in ECR (phase 2 — automatic on full install, or python cdk_install.py --complete-agentcore).
pi or langgraph: orchestration runs inside the agent container. The agent calls the main app at http://<ECS_SERVICE_CONNECT_DISCOVERY_NAME>:7860 (default http://redaction:7860) over Service Connect, configured in post_cdk_build_quickstart.py after images are built.

When to use: pilots or demos where the main app is already on Express and you want a separate agentic UI without legacy Fargate or ALB path/host routing.

Installer: on the Demonstration profile, answer yes to “Deploy agentic redaction (second Gradio app on Express…)” or use --enable-agentic / --enable-agentic-express. The wizard then asks for orchestration backend (AgentCore, Pi, or LangGraph), Service Connect discovery name (default redaction), agent Gradio port (default 7862), and (for AgentCore) Bedrock model. It does not prompt for AGENT_ALB_ROUTING (that applies to legacy Fargate agentic mode only).

Requirements:

USE_ECS_EXPRESS_MODE=True and ACM_SSL_CERTIFICATE_ARN empty
ENABLE_PI_AGENT_EXPRESS_SERVICE=True (not ENABLE_PI_AGENT_ECS_SERVICE)
Build and push the agent image before scaling ECS_PI_EXPRESS_SERVICE_NAME; build AgentCore runtime image when AGENTCORE_CDK_DEPLOY=True
aws-cdk-lib 2.230+; see cdk/docs/express_pi_service_connect_spike.md if Service Connect is missing in the console (re-run quickstart)

Key cdk_config.env flags (AgentCore demo):

USE_ECS_EXPRESS_MODE=True
ENABLE_PI_AGENT_EXPRESS_SERVICE=True
AGENT_ORCHESTRATOR=agentcore
ENABLE_AGENTCORE_RUNTIME=True
AGENTCORE_CDK_DEPLOY=True
AGENTCORE_BEDROCK_MODEL=anthropic.claude-sonnet-4-6

Stack outputs: AgenticExpressEndpoint, AgentRedactionLoginUrl (magic-link demo), PiPublicUrl, PiDocRedactionBackendUrl, PiExpressServiceName, ServiceConnectNamespace, AgentCoreRuntimeArn (when CDK AgentCore deploy is on)

Workspace: Express agent tasks have no Fargate volume mounts; CDK sets AGENT_WORKSPACE_DIR=/tmp/agent-workspace and related paths under /tmp.

Cognito / magic-link: With magic-link CloudFront, open AgentRedactionLoginUrl once, then use AgenticExpressEndpoint. With Cognito on the agent URL, register users in the same user pool and add callback URLs as needed. Main app in-app auth is off when agentic Express is on (see above).

Bedrock AgentCore runtime

Amazon Bedrock AgentCore runs the LangGraph redaction agent separately from the Gradio UI. The UI (AGENT_ORCHESTRATOR=agentcore) streams prompts to the runtime via AGENTCORE_RUNTIME_URL.

CDK two-phase deploy (recommended on demo):

Phase 1 (cdk deploy + quickstart): CodeBuild packages agent-redact/agentcore into an ARM64 image and pushes to {CDK_PREFIX}agentcore-runtime ECR. CDK also creates IAM roles and (optionally) a CfnRuntime when ENABLE_AGENTCORE_CDK_RUNTIME=True.
Phase 2 (after ECR image exists): cdk_install.py calls the bedrock-agentcore-control API to create the runtime, derives AGENTCORE_RUNTIME_URL, and updates config/agent.env. If phase 2 is skipped (image still building), run python cdk_install.py --complete-agentcore.

Phase 2 intentionally avoids a second cdk deploy of RedactionStack (which could flip managed resources to imports on demo stacks).

Manual CLI deploy (no CDK runtime provisioning): package and deploy with the AgentCore CLI — see agent-redact/agentcore/README.md. Then pass --agentcore-runtime-url or set AGENTCORE_RUNTIME_URL in config/agent.env.

Backend URL for AgentCore tools: the runtime must call the main doc_redaction Gradio API (/doc_redact, /review_apply). CDK sets DOC_REDACTION_GRADIO_URL to the main public HTTPS endpoint (ExpressServiceEndpoint or CloudFront URL), not http://redaction:7860 Service Connect.

Auth: on AWS ECS the agent task role typically uses IAM SigV4 to invoke AgentCore (bedrock-agentcore:InvokeAgentRuntime). AGENTCORE_API_KEY is only needed for runtimes using CUSTOM_JWT bearer auth.

Key cdk_config.env flags:

AGENT_ORCHESTRATOR=agentcore
ENABLE_AGENTCORE_RUNTIME=True
AGENTCORE_CDK_DEPLOY=True
AGENTCORE_BEDROCK_MODEL=anthropic.claude-sonnet-4-6
# AGENTCORE_RUNTIME_URL=   # set automatically after phase 2

ECS Service Connect (VPC service-to-service API)

ECS Service Connect lets other ECS services in the same cluster and namespace call this app over HTTP using a short DNS name, without going through CloudFront or Cognito. This suits programmatic access when RUN_FASTAPI=True in config.env (Agent API under /agent/...) or the Gradio HTTP API under /gradio_api/....

When to use: another microservice in the same VPC needs to call redaction programmatically (e.g. POST http://redaction:7860/agent/redact_document).

Requirements:

ENABLE_ECS_SERVICE_CONNECT=True
USE_ECS_EXPRESS_MODE=False (or unset)
Legacy Fargate service created by CDK (not an imported existing service unless you enable Service Connect on it manually in the console)
At least one client security group (see below)—traffic is allowed only from those groups, not from the whole VPC
Calling services must also use Service Connect in the same ECS_SERVICE_CONNECT_NAMESPACE (default derived from CDK_PREFIX, e.g. lambeth-redaction-local)

Client security groups (pick one or combine; pre-check resolves names in your VPC):

ENABLE_ECS_SERVICE_CONNECT=True

# (A) Recommended: CDK_PREFIX values of other apps that use the same ECS security group naming pattern
#     ({prefix}SecurityGroupECS, matching this stack's ECS security group name)
ECS_SERVICE_CONNECT_CLIENT_CDK_PREFIXES=Lambeth-AWS-SharedServices-Dev-OtherApp-

# (B) Explicit security group names in VPC_NAME
ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_NAMES=MyCallerService-SecurityGroupECS

# (C) Explicit security group IDs (no lookup)
ECS_SERVICE_CONNECT_CLIENT_SECURITY_GROUP_IDS=sg-0123456789abcdef0

Run python check_resources.py from the cdk folder before cdk deploy so security group names are resolved into precheck.context.json. CDK fails at synth if Service Connect is on but no client groups could be resolved.

Optional tuning:

ECS_SERVICE_CONNECT_DISCOVERY_NAME=redaction   # clients use http://redaction:7860
ECS_SERVICE_CONNECT_NAMESPACE=lambeth-redaction-local
ECS_SERVICE_CONNECT_PORT_MAPPING_NAME=port-7860   # must match the Fargate port mapping name

Stack outputs: ServiceConnectHttpBaseUrl, ServiceConnectAgentApiUrl, ServiceConnectNamespace.

Important: Service Connect traffic bypasses ALB Cognito. Use the Agent API with AGENT_API_KEY (if configured in your environment) or appropriate auth for service-to-service calls—not the browser login flow.

Agentic redaction on ECS (shared ALB + Service Connect backend)

Deploy the agent Gradio app as a second Fargate service in the same cluster. The agent UI is exposed on the same Application Load Balancer as the main redaction app. By default CDK uses path routing (AGENT_ALB_ROUTING=path, AGENT_ALB_PATH_PREFIX=/agent) so the UI is at https://<CLOUDFRONT_DOMAIN>/agent/ when you use the CloudFront URL. Optional host-header routing (AGENT_ALB_ROUTING=host or both + AGENT_ALB_HOST_HEADER) remains available for a dedicated hostname on the ACM cert.

With AGENT_ORCHESTRATOR=pi or langgraph, the agent calls the main app over Service Connect using gradio_client (/doc_redact, /review_apply) — not the FastAPI /agent/* routes on the main service. With agentcore, the Gradio UI proxies to AgentCore; the runtime uses the public main app URL.

When to use: agentic document redaction with Amazon Bedrock orchestration while keeping heavy OCR/PII on the existing main service.

Requirements:

ENABLE_PI_AGENT_ECS_SERVICE=True
USE_ECS_EXPRESS_MODE=False
ENABLE_ECS_SERVICE_CONNECT=True on the main service
AGENT_ALB_ROUTING — path (default), host, or both
AGENT_ALB_PATH_PREFIX=/agent when routing includes path (legacy installs may still use /pi)
AGENT_ALB_HOST_HEADER when routing is host or both (DNS CNAME → same ALB)
ACM_SSL_CERTIFICATE_ARN on the shared HTTPS listener (recommended; agent path gets Cognito-on-ALB like the main app)
Build and push the agent image before scaling the agent service
Upload config/agent.env to the log/config S3 bucket (PI_AGENT_ENV_S3_KEY — legacy key name)

Example cdk_config.env additions: see cdk/cdk_config.py and config/agent.env.example.

Stack outputs: PiPublicUrl, PiAlbPathPrefix, PiDocRedactionBackendUrl (internal http://redaction:7860 for Pi/LangGraph), ECRPiRepoUri, PiAgentServiceName.

Cognito: For path routing, use the same callback URLs as the main CloudFront host (https://<CLOUDFRONT_DOMAIN>/oauth2/idpresponse). For a dedicated agent host, add https://<AGENT_ALB_HOST_HEADER>/oauth2/idpresponse too.

Note: CDK sets AGENT_ROOT_PATH / ROOT_PATH on agent tasks when path routing is enabled so Gradio assets resolve under /agent/.

Headless batch deployment (S3 → Lambda → one-shot ECS)

Headless mode deploys the redaction task definition and supporting AWS resources without an always-on browser-facing ECS service, Express endpoint, or Cognito hosted UI login. Jobs are triggered when you upload a small .env file to the output S3 bucket under the batch prefix; a Lambda starts a one-shot Fargate task with RUN_DIRECT_MODE=True (same behaviour as cli_redact.py / direct mode in app.py).

When to use: pipeline or batch workloads, automation, or environments where no human uses the Gradio UI.

How to enable via installer:

Dedicated profile: choose “Headless batch only” (profile 3) or python cdk_install.py --profile headless …
Add-on to production: on the Production profile, answer yes to “Enable headless batch-only deployment…” or pass --profile production --headless
Custom: turn off ECS Express, then enable headless in the wizard or use --headless

Not compatible with: Demonstration (Express) profile, USE_ECS_EXPRESS_MODE=True, CloudFront, agentic redaction (Express or legacy), or ECS Service Connect. The installer skips Cognito domain prefix prompts and agentic options in headless mode.

Key cdk_config.env flags (set automatically by the headless preset):

ENABLE_HEADLESS_DEPLOYMENT=True
ENABLE_S3_BATCH_ECS_TRIGGER=True
USE_ECS_EXPRESS_MODE=False
USE_CLOUDFRONT=False
COGNITO_AUTH=False

After deploy: run post_cdk_build_quickstart.py to build the container image in CodeBuild (it does not scale an always-on service). Upload job files to s3://<output-bucket>/<S3_BATCH_ENV_PREFIX>*<suffix> (see stack output BatchJobEnvPrefix). See S3 batch ECS trigger for job file format.

CDK prefix note: resource names (including COGNITO_USER_POOL_NAME, e.g. {CDK_PREFIX}UserPool) follow CDK_PREFIX. If you previously deployed a Headless-Redaction- stack and later switch to Demo-Redaction-, run python check_resources.py again so precheck.context.json does not reuse stale “exists” entries from the old prefix.

S3 batch ECS trigger (one-shot direct-mode tasks)

When ENABLE_S3_BATCH_ECS_TRIGGER=True, CDK deploys a Lambda that listens for new objects on the output S3 bucket under S3_BATCH_ENV_PREFIX (default input/config/) with suffix .env. Each upload starts an additional Fargate task using the same task definition as the web service, with container overrides that set RUN_DIRECT_MODE=True and job-specific DIRECT_MODE_* variables (same behaviour as app.py direct mode / cli_redact.py).

This is the runtime path for headless deployments (ENABLE_HEADLESS_DEPLOYMENT=True). You can also enable the S3 batch trigger on a full production stack without enabling full headless (no always-on UI), via the installer add-on or ENABLE_S3_BATCH_ECS_TRIGGER=True in cdk_config.env.

When to use: batch or pipeline workflows that drop a small job config next to input files in S3, without calling the Gradio UI or Agent API.

Requirements:

ENABLE_S3_BATCH_ECS_TRIGGER=True
USE_ECS_EXPRESS_MODE=False (legacy Fargate task definition required for ecs.run_task)
Legacy Fargate path deployed by CDK (cluster, task definition, private subnets, ECS security group)
Input documents under the output bucket prefix S3_BATCH_INPUT_PREFIX (default input/)
Optional shared defaults at S3_BATCH_DEFAULT_PARAMS_KEY on the output bucket (e.g. general-config/batch_defaults.env)

Example job file (s3://<output-bucket>/input/config/case-001.env):

DIRECT_MODE_INPUT_FILE=case-001/document.pdf
DIRECT_MODE_TASK=redact
DIRECT_MODE_PAGE_MIN=1
DIRECT_MODE_PAGE_MAX=10

Relative paths are expanded to s3://<output-bucket>/input/... for input files and s3://<log-bucket>/... for deny/allow list paths. The long-running ECS service can stay at desired count 1; each .env upload spawns a separate task (plan capacity accordingly).

Example cdk_config.env additions: see cdk/cdk_config.py (search for S3_BATCH_ keys).

Stack outputs: BatchEcsTriggerLambdaArn, BatchJobEnvPrefix (full S3 URI prefix for uploads).

Note: The task still loads app_config.env from the log bucket via environmentFiles on the legacy path; container overrides take precedence for batch keys. Do not set RUN_DIRECT_MODE=False in job files.

Steps to install the app using CDK manually

These steps are for a manual install. If you used cdk_install.py, steps 1.a, 1.b, and 2 are already done; jump to step 3 or rely on the installer’s deploy and quickstart.

1.a Create a python environment, load in packages from `requirements.txt`.

You will need to install into a python environment with the requirements detailed in cdk/requirements.txt. In your Python environment, cd to this folder and run pip install -r requirements.txt

1.b Create a cdk.json file

After this, you need a cdk.json in the cdk folder. It should contain the following:

{
    "app": "<PATH TO PYTHON ENVIRONMENT FOLDER WHERE REQUIREMENTS HAVE BEEN LOADED>/python.exe app.py",
    "context": {
        "@aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId": true,
        "@aws-cdk/core:stackRelativeExports": true,
        "@aws-cdk/aws-rds:lowercaseDbIdentifier": true,
        "@aws-cdk/aws-lambda:recognizeVersionProps": true,
        "@aws-cdk/aws-lambda:recognizeLayerVersion": true,
        "@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021": true,
        "@aws-cdk/aws-ecs:arnFormatIncludesClusterName": true,
        "@aws-cdk/core:newStyleStackSynthesis": true,
        "aws-cdk:enableDiffNoFail": true,
        "@aws-cdk/aws-ec2:restrictDefaultSecurityGroup": true,
        "@aws-cdk/aws-apigateway:disableCloudWatchRole": true,
        "@aws-cdk/core:target-partitions": [
        "aws",
        "aws-cn"
        ]
    }
    }

2. Create a `cdk_config.env` file in the `config` subfolder.

Depending on which environment variables you put in this file, you can choose whether to install the app in a completely new VPC, or in an existing VPC. The following shows you example config files that you could use.

Deploying the app an a brand new VPC

Here as a minimum it would be useful to put the following details in the cdk_config.env file (below are all example values, other possible variables to use here can be seen in the cdk folder/cdk_config.py).

CDK_PREFIX=example-prefix # This prefix will be added to the name of most of the created elements in your stack
NEW_VPC_CIDR=10.0.0.0/24 # The CIDR range for your newly created VPC
AWS_REGION=<your-region> # Region where elements will be created
AWS_ACCOUNT_ID=1234567890 # AWS account ID that has administrator access that you will use for deploying the stack
CDK_FOLDER=C:/path_to_cdk_folder/ # The place where the cdk folder code is located
CONTEXT_FILE=C:/path_to_cdk_folder/cdk.context.json
COGNITO_USER_POOL_DOMAIN_PREFIX=redaction-12345 # The prefix of the login / user sign up domain that you want to use with Cognito login. Should not contain the terms amazon, aws, or cognito.
COGNITO_AUTH=0 # Do you want to do in-app authentication (username and password only, not necessary if you are using an SSL certificate as recommended below)  
USE_CLOUDFRONT=True # Recommended. If you intend to use CloudFront as the front URL to your application load balancer (ALB). This has some extra security features that you won't get with just an ALB, e.g. limiting app access by country.
RUN_USEAST_STACK=False # Set this to True only if you have permissions to create a Cloudfront distribution and web ACL on top of it in the us-east-1 region. If you don't, the section below shows how you can create the CloudFront resource manually and map it to your application load balancer (as you should have permissions for that if you are admin in your region).
CLOUDFRONT_DOMAIN=<example>.cloudfront.net # If you already know the domain of the CloudFront distribution that you want to use, you can add this here.
# Optional: CSP and security response headers on the CDK CloudFront stack (default on when RUN_USEAST_STACK=True):
# CLOUDFRONT_ENABLE_SECURE_RESPONSE_HEADERS=True
# COGNITO_USER_POOL_LOGIN_URL=  # leave empty to derive from COGNITO_USER_POOL_DOMAIN_PREFIX + AWS_REGION
# If you are using an SSL certificate with your ALB (highly recommended for production):
ACM_SSL_CERTIFICATE_ARN=<SSL Certificate ARN> # This is the ARN of the SSL certificate that you have installed in AWS Certificate Manager
SSL_CERTIFICATE_DOMAIN=redaction.example.com # This is the domain of the SSL certificate that you have installed in AWS Certificate Manager

# Optional: ECS Express Mode instead of ACM (pilot/dev only — see "ECS Express Mode" above):
# USE_ECS_EXPRESS_MODE=True

# Optional: VPC service-to-service API for other ECS tasks (legacy Fargate only — see "ECS Service Connect" above):
# ENABLE_ECS_SERVICE_CONNECT=True
# ECS_SERVICE_CONNECT_CLIENT_CDK_PREFIXES=OtherApp-CDK-Prefix-

# Optional: agentic redaction UI on the same ALB (see "Agentic redaction on ECS" above):
# ENABLE_PI_AGENT_ECS_SERVICE=True
# AGENT_ALB_HOST_HEADER=agent.redaction.example.com
# AGENT_ORCHESTRATOR=pi

# Optional: headless batch only (see "Headless batch deployment" above):
# ENABLE_HEADLESS_DEPLOYMENT=True
# ENABLE_S3_BATCH_ECS_TRIGGER=True
# USE_ECS_EXPRESS_MODE=False

Note: If you are using an SSL certificate with Cognito login on the application load balancer (strongly advised), you can set COGNITO_AUTH to 0 above, as you don’t need the second login step to get to the app

Note: Do not set USE_ECS_EXPRESS_MODE=True together with ACM_SSL_CERTIFICATE_ARN or ENABLE_ECS_SERVICE_CONNECT=True.

In an existing VPC

From the above example, remove the variable ‘NEW_VPC_CIDR’ and replace with the below:

VPC_NAME=example-vpc-name # Name of the VPC within which all the other elements will be created
EXISTING_IGW_ID=igw-1234567890 # Internet Gateway for public subnets (legacy path). Pre-check verifies attachment to VPC_NAME and 0.0.0.0/0 routes; CDK attaches the IGW and adds missing routes on deploy when needed.
SINGLE_NAT_GATEWAY_ID=nat-123456789 # (optional) The ID for an existing NAT gateway that you want to use instead of creating a new one

Subnets

If you are using an existing VPC then you may want to deploy the app within existing subnets rather than creating new ones:

If you define no subnets in environment variables, the app will try to use existing private and public subnets. Bear in mind the app may overlap with IP addresses assigned to existing AWS resources. It is advised to at least specify existing subnets that you know are available, or create your own using one of the below methods.
If you want to use existing subnets, you can list them in the following environment variables:

PUBLIC_SUBNETS_TO_USE=["PublicSubnet1", "PublicSubnet2", "PublicSubnet3"]`
PRIVATE_SUBNETS_TO_USE=["PrivateSubnet1", "PrivateSubnet2", "PrivateSubnet3"]`

If you want to create new subnets, you need to also specify CIDR blocks and availability zones for the new subnets. The app will check with you upon deployment whether these CIDR blocks are available before trying to create.

PUBLIC_SUBNET_CIDR_BLOCKS=['10.222.333.0/28', '10.222.333.16/28', '10.222.333.32/28']
PUBLIC_SUBNET_AVAILABILITY_ZONES=['eu-east-1a', 'eu-east-1b', 'eu-east-1c']
PRIVATE_SUBNET_CIDR_BLOCKS=['10.222.333.48/28', '10.222.333.64/28', '10.222.333.80/28']
PRIVATE_SUBNET_AVAILABILITY_ZONES=['eu-east-1a', 'eu-east-1b', 'eu-east-1c']

If you try to create subnets in invalid CIDR blocks / availability zones, the console output will tell you and it will show you the currently occupied CIDR blocks to help find a space for new subnets you want to create.

Internet Gateway (legacy ALB in public subnets): Run python check_resources.py before cdk deploy. It audits each named public subnet’s route table. If EXISTING_IGW_ID is set but not attached to the VPC, CDK creates AWS::EC2::VPCGatewayAttachment. If a subnet’s route table lacks 0.0.0.0/0 → that IGW, CDK adds AWS::EC2::Route. Pre-check fails if a public route table already has a conflicting default route (for example NAT or a different IGW).

3. Run pre-check and deploy your AWS stack

In command line, go to your cdk folder in the redaction app folder.

If you use ECS Service Connect or rely on security group name resolution, run the pre-check script first (writes precheck.context.json):

python check_resources.py

Then deploy:

cdk deploy --all

This deploys the stacks defined in app.py (RedactionStack, and optionally RedactionStackCloudfront and AppRegistryStack).

Hopefully everything will deploy successfully and you will be able to see your new stacks in CloudFormation in the AWS console. There should be one called RedactionStack and one called RedactionStackCloudfront if you set RUN_USEAST_STACK to ‘True’ in config/cdk_config.env. You will also see a stack called AppRegistryStack if you set ENABLE_APPREGISTRY to ‘True’ in the same config file.

AWS Console myApplications (optional, enabled by default)

When ENABLE_APPREGISTRY=True in config/cdk_config.env (off by default — AWS is retiring creation of new AppRegistry Applications), CDK also registers the regional stack with AWS Service Catalog AppRegistry, which powers the Applications widget on the AWS console home page and Application Manager.

After deploy you should see an application named {CDK_PREFIX}doc-redaction (or your APPREGISTRY_APPLICATION_NAME) listing RedactionStack resources and their live AWS status—for example the application load balancer, ECS cluster and service, Cognito user pool, S3 buckets, and CodeBuild project.

Console path: Application Manager (or the home page Applications section).
The associator stack (default name {CDK_PREFIX}AppRegistryStack) outputs a deep link to the application in Application Manager.
CloudFront (phase 1): If you deploy RedactionStackCloudfront in us-east-1, it is not included in this myApplications entry (AppRegistry does not support cross-region stack association via CDK). View CloudFront and WAF in the us-east-1 CloudFormation console (RedactionStackCloudfront) or the CloudFront console.
To disable: set ENABLE_APPREGISTRY=False in config/cdk_config.env and redeploy.

Optional variables (see cdk/cdk_config.py): APPREGISTRY_APPLICATION_NAME, APPREGISTRY_DESCRIPTION, APPREGISTRY_STACK_NAME, APPREGISTRY_ATTRIBUTE_GROUP_NAME, APPREGISTRY_REPOSITORY_URL.

4. Tasks for after CDK deployment

The CDK deployment creates the AWS resources needed to run the redaction app. Some steps still require manual action or a follow-up script.

Run `post_cdk_build_quickstart.py`

The following tasks are done by the post_cdk_build_quickstart.py file that you can find in the cdk folder. You will need to run this when logged in with AWS SSO through command line. I will describe how to do this in AWS console just in case the .py file doesn’t work for you.

Codebuild

You need to build CodeBuild project after stack has finished deploying your CDK stack, as there will be no container in ECR.

If you don’t want to run the ‘post_cdk_build_quickstart.py’ file, in console, go to CodeBuild -> your project -> click Start build. Check the logs, the build should complete in about 6-7 minutes.

Create `app_config.env` and upload to S3

The post_cdk_build_quickstart script creates/updates cdk/config/app_config.env and uploads it to S3. On the legacy Fargate path, the task definition loads that file from S3 at runtime via environmentFiles.

On the ECS Express Mode path, CDK already inlined app_config.env variables as container environment variables at deploy time; keep the file in sync and redeploy after major config changes. Uploading to S3 is still useful for documentation and parity with the quickstart script.

Repo-wide OCR/PII settings remain in config/config.env at the repository root (local dev and image build); do not confuse that file with cdk/config/app_config.env, which carries AWS deployment keys (COGNITO_AUTH, bucket names, DynamoDB table names, etc.).

If you want to set AWS deployment keys manually, create or edit cdk/config/app_config.env with at least:

COGNITO_AUTH=False # If you are using an SSL certificate with your application load balancer, you will be logging in there. Set this to 0 to turn off the default login screen.
RUN_AWS_FUNCTIONS=True # This will enable the app to communicate with AWS services.
SESSION_OUTPUT_FOLDER=True # This will put outputs for each user in separate output folders.

Then, go to S3 and choose the new ...-logs bucket that you created. Upload app_config.env into this bucket (same basename as APP_CONFIG_ENV_BASENAME in CDK config).

Update Elastic Container Service

Now that the app container is in Elastic Container Registry, you can run the app on Fargate.

The post_cdk_build_quickstart.py file will scale the service for you. You can also do this in the console: ECS → your cluster → your service ({CDK_PREFIX}ECSService on the legacy path, or the Express service name from ECS_EXPRESS_SERVICE_NAME) → Update service → Force new deployment → set Desired number of tasks to 1.

Service Connect: After the service is running, other ECS services in the same Service Connect namespace can call the URLs from stack outputs (ServiceConnectAgentApiUrl, etc.). Ensure those client tasks use a security group you listed in ECS_SERVICE_CONNECT_CLIENT_* settings.

Additional Manual Tasks

Update DNS records for your domain (If using a domain for the SSL certificate)

If the SSL certificate you are using is associated with a domain, you will need to update the DNS records for your domain registered with the AWS SSL certificate. To do this, you need to create a CNAME DNS record for your domain pointing to your load balancer DNS from a subdomain of your main domain registration, e.g., redaction.<domain-name>.

Create a user in Cognito

You will next need to a create a user in Cognito to be able to log into the app.

Go to Cognito and create a user with your own email address. Generate a password.
Go to Cognito -> App clients -> Login pages -> View login page.
Enter the email and temporary password details that come in the email (don’t include the last full stop!).
Change your password on the screen that pops up. You should now be able to login to the app.

Set Multi-Factor Authentication for Cognito logins(optional but recommended)

On the Cognito user pool page you can also enable MFA, if you are using an SSL certificate with Cognito login on the Application Load Balancer. Go to Cognito -> your user pool -> Sign in -> Multi-factor authentication.

Create CloudFront distribution

Note: this is only relevant if you set RUN_USEAST_STACK to ‘False’ during CDK deployment

If you were not able to create a CloudFront distribution via CDK, you should be able to do it through console. I would advise using CloudFront as the front end to the app.

Create a new CloudFront distribution.

If you have used an SSL certificate in your CDK code:
- For Origin:
  - Choose the domain name associated with the certificate as the origin.
  - Choose HTTPS only as the protocol.
  - Keep everything else default.
- For Behavior (modify default behavior):
  - Under Viewer protocol policy choose ‘Redirect HTTP to HTTPS’.
If you have not used an SSL certificate in your CDK code:
- For Origin:
  - Choose your elastic load balancer as the origin. This will fill in the elastic load balancer DNS.
  - Choose HTTP only as the protocol.
  - Keep everything else default.
- For Behavior (modify default behavior):
  - Under Viewer protocol policy choose ‘HTTP and HTTPS’.

Security features

You can add security features to your CloudFront distribution (recommended). If you use WAF, you will also need to change the default settings to allow for file upload to the app.

In your CloudFront distribution, under ‘Security’ -> Edit -> Enable security protections.
Choose rate limiting (default is fine). Then click Create.
In CloudFront geographic restrictions -> Countries -> choose an Allow list of countries.
Click again on Edit.
In AWS WAF protection enabled you should see a link titled ‘View details of your configuration’.
Go to Rules -> AWS-AWSManagedRulesCommonRuleSet, click Edit.
Under SizeRestrictions_BODY choose rule action override ‘Override to Allow’. This is needed to allow for file upload to the app.

Content Security Policy (CSP) and response headers

If you deploy CloudFront with CDK (RUN_USEAST_STACK=True and USE_CLOUDFRONT=True), the RedactionStackCloudfront stack can attach a response headers policy (CSP, HSTS, CORS, Permissions-Policy, and related headers) that matches the template in cdk/config/response-headers-policy-config.json. CDK substitutes URLs from your existing cdk_config.env values:

Placeholder in the JSON template	CDK / config source
`{APP-URL}` (CORS allow origin)	`COGNITO_REDIRECTION_URL` (preferred), else `https://` + `SSL_CERTIFICATE_DOMAIN`, else `https://` + `CLOUDFRONT_DOMAIN`
`{APP-URL}` (CSP `connect-src` WebSocket host)	Hostname of that same app origin (`wss://…`)
`{COGNITO-APP-CLIENT-LOGIN-URL}` (CSP `manifest-src`)	`COGNITO_USER_POOL_LOGIN_URL` if set, else `https://<COGNITO_USER_POOL_DOMAIN_PREFIX>.auth.<AWS_REGION>.amazoncognito.com`

Set CLOUDFRONT_ENABLE_SECURE_RESPONSE_HEADERS=False in cdk_config.env to skip this policy. After your real CloudFront domain or custom CNAME is known, set CLOUDFRONT_DOMAIN and COGNITO_REDIRECTION_URL (and Cognito callback URLs) to match, then redeploy the us-east-1 CloudFront stack so CORS/CSP origins stay correct.

If you create CloudFront manually (console), attach the same policy yourself:

Open cdk/config/response-headers-policy-config.json and replace placeholders:
- {APP-URL} in CORS → full browser origin, e.g. https://d111111abcdef8.cloudfront.net or https://redaction.example.com (scheme required).
- {APP-URL} in CSP connect-src → hostname only (no https://), e.g. d111111abcdef8.cloudfront.net, because the template already prefixes wss://.
- {COGNITO-APP-CLIENT-LOGIN-URL} → Cognito hosted UI base URL from Cognito → App integration → Domain (or the CognitoUserPoolLoginUrl stack output), e.g. https://<COGNITO_USER_POOL_DOMAIN_PREFIX>.auth.<region>.amazoncognito.com.
Create the policy in the AWS CLI (global CloudFront API), using only the ResponseHeadersPolicyConfig object (omit ETag from the downloaded file):

aws cloudfront create-response-headers-policy ^
  --response-headers-policy-config file://response-headers-policy-config-only.json

To build response-headers-policy-config-only.json, copy ResponseHeadersPolicyConfig from the template file and apply the substitutions above. Note the policy Name must be unique in your account.

In CloudFront → your distribution → Behaviors → Edit default behavior, set Response headers policy to the policy you created.
If the browser blocks Gradio WebSockets or Cognito login, open developer tools → Network, note the blocked URL, and extend connect-src / manifest-src in the policy (then update the policy with update-response-headers-policy and the policy ETag).

You can export an existing policy for editing:

aws cloudfront list-response-headers-policies --type custom
aws cloudfront get-response-headers-policy --id POLICY_ID --output json > policy.json

Change Cognito redirection URL to your CloudFront distribution

Go to Cognito -> your user pool -> App Clients -> Login pages -> Managed login configuration.

Ensure that the callback URL is: * If not using an SSL certificate and Cognito login - https://<CloudFront domain name> * If using an SSL certificate, you should have three: * https://<CloudFront domain name> * https://<CloudFront domain name>/oauth2/idpresponse

Using your custom URL as the frontend to your CloudFront distribution (and app)

You may want to access your app via a custom URL. To do this:

Create an ACM certificate in us-east-1 for your custom domain (e.g. *.<domain-name>). This should use the same settings as the certificate set up for the application load balancer in your home region.
Go to CloudFront, then select your distribution. On the general settings page, click Edit.
Under Alternate domain names (CNAMEs) add your custom domain (e.g. redaction.<domain-name>).
Under SSL certificate, choose ‘Custom SSL certificate’ and select the certificate you just created in us-east-1.
Click save changes.
Ensure the Cognito callback URLs include the new custom domain (e.g. https://redaction.<domain-name> and https://redaction.<domain-name>/oauth2/idpresponse).
Update COGNITO_REDIRECTION_URL and CLOUDFRONT_DOMAIN in cdk_config.env to the custom domain, redeploy RedactionStackCloudfront if you use CDK-managed CSP, or edit your manual response headers policy so CORS and CSP connect-src / wss:// use the new host.

Force traffic to come from specific CloudFront distribution (optional)

Note that this only potentially helps with security if you are not using an SSL certificate with Cognito login on your application load balancer.

Go to EC2 - Load Balancers -> Your load balancer -> Listeners -> Your listener -> Add rule.

Add Condition -> Host header.
Change Host header value to your CloudFront distribution without the https:// or http:// at the front.
Forward to redaction target group.
Turn on group stickiness for 8 hours.
Next.
Choose priority 1.

Then, change the default listener rule.

Under Routing action change to ‘Return fixed response’.

You should now have successfully installed the document redaction app in an AWS environment using CDK.

Installation with CDK

Quick start with cdk_install.py

What the script does

Deployment profiles

Common commands

After the installer finishes

Prerequisites

Note on ACM Certificates

Optional deployment modes

ECS Express Mode (HTTPS without your own ACM certificate)

Agentic redaction on ECS Express (dedicated HTTPS URL)

Bedrock AgentCore runtime

ECS Service Connect (VPC service-to-service API)

Agentic redaction on ECS (shared ALB + Service Connect backend)

Headless batch deployment (S3 → Lambda → one-shot ECS)

S3 batch ECS trigger (one-shot direct-mode tasks)

Steps to install the app using CDK manually

1.a Create a python environment, load in packages from requirements.txt.

1.b Create a cdk.json file

2. Create a cdk_config.env file in the config subfolder.

Deploying the app an a brand new VPC

In an existing VPC

Subnets

3. Run pre-check and deploy your AWS stack

AWS Console myApplications (optional, enabled by default)

4. Tasks for after CDK deployment

Run post_cdk_build_quickstart.py

Codebuild

Create app_config.env and upload to S3

Update Elastic Container Service

Additional Manual Tasks

Update DNS records for your domain (If using a domain for the SSL certificate)

Create a user in Cognito

Set Multi-Factor Authentication for Cognito logins(optional but recommended)

Create CloudFront distribution

Security features

Content Security Policy (CSP) and response headers

Change Cognito redirection URL to your CloudFront distribution

Using your custom URL as the frontend to your CloudFront distribution (and app)

Force traffic to come from specific CloudFront distribution (optional)

Quick start with `cdk_install.py`

1.a Create a python environment, load in packages from `requirements.txt`.

2. Create a `cdk_config.env` file in the `config` subfolder.

Run `post_cdk_build_quickstart.py`

Create `app_config.env` and upload to S3