AWS ECS Fargate Deployment
Relevant source files
The following files were used as context for generating this wiki page:
The AWS ECS Fargate deployment for pi-digby provides a serverless, containerized infrastructure for running a Slack bot powered by Amazon Bedrock. This system leverages AWS CloudFormation to define a robust environment including networking, persistent storage via EFS, and secure secrets management.
The deployment is designed for high availability and persistence, ensuring that agent memory, logs, and configuration survive container restarts by utilizing Amazon Elastic File System (EFS). It operates in Slack Socket Mode, meaning it does not require a public inbound endpoint for Slack interactions, though it does support optional webhooks via Cloudflare Tunnels or a local HTTP server for health checks.
Sources: CLAUDE.md:1-20, deploy/cloudformation.yml:1-10
Infrastructure Architecture
The infrastructure is defined as an AWS CloudFormation stack that creates a dedicated Virtual Private Cloud (VPC) with public subnets across two availability zones.
The diagram above illustrates the network isolation and the primary AWS service integrations used by the Fargate task.
Networking Components
The deployment uses a standard public-facing VPC structure to allow the bot to egress to Slack and AWS APIs.
| Component | Resource Type | Description |
|---|---|---|
| VPC | AWS::EC2::VPC | 10.0.0.0/16 CIDR block with DNS support. |
| Subnets | AWS::EC2::Subnet | Two public subnets (us-east-1a, us-east-1b) with public IP mapping enabled. |
| Security Group (ECS) | AWS::EC2::SecurityGroup | Allows all egress; used by Fargate tasks. |
| Security Group (EFS) | AWS::EC2::SecurityGroup | Allows inbound NFS (port 2049) from the ECS Security Group. |
Sources: deploy/cloudformation.yml:14-118
Compute and Containerization
The core logic runs within an Amazon ECS Cluster named pi-digby using the Fargate capacity provider.
Task Definition
The ECS Task Definition specifies the resource requirements and container environment:
- CPU/Memory: 1024 CPU units and 2048 MiB memory.
- Image: Hosted in a dedicated Amazon ECR repository (
pi-digby). - Network Mode:
awsvpcfor direct VPC integration. - Health Check: A
curlcommand againsthttp://localhost:8080/healthdetermines container vitality.
Sources: deploy/cloudformation.yml:320-410, src/main.ts:250-255
Storage and Persistence
Persistence is achieved by mounting an EFS volume to /data within the container. This directory stores channel-specific logs, memory, and tool-related data.
The persistent storage ensures that even when the Fargate task is replaced during a deployment or failure, the agent retains its state.
Sources: CLAUDE.md:10-15, deploy/cloudformation.yml:335-345, entrypoint.sh:5-15
Security and IAM Roles
The deployment implements the principle of least privilege using several distinct IAM roles.
Task Execution Role
Used by the ECS agent to pull images from ECR and fetch secrets from Secrets Manager. It includes the AmazonECSTaskExecutionRolePolicy and specific access to the pi-digby/env secret.
Task Role
Used by the running application. Critically, this role provides the permissions to call Amazon Bedrock without requiring hardcoded IAM user credentials.
- Bedrock:
bedrock:InvokeModelandbedrock:InvokeModelWithResponseStream. - ECS Exec: Permissions for
ssmmessagesto allow interactive debugging. - Observability: Permissions to read its own CloudWatch logs and ECS task descriptions.
Sources: deploy/cloudformation.yml:185-260, src/agent/setup.ts:35-45
Deployment Workflow
The project uses GitHub Actions for CI/CD, which interacts with the AWS environment via OIDC.
GitHub Deployment Role
The GitHubDeployRole allows GitHub Actions to assume a role via OIDC to:
- Push images to ECR.
- Register new ECS Task Definitions.
- Update the ECS Service.
- Execute CloudFormation change sets.
Sources: deploy/cloudformation.yml:272-315, CLAUDE.md:52-55
Boot Sequence and Entrypoint
The entrypoint.sh script prepares the persistent environment before starting the Node.js application.
#!/bin/sh
# Persist ~/.pi on EFS so MCP config, auth tokens survive restarts
mkdir -p /data/.pi
ln -sfn /data/.pi /root/.pi
# Seed MCP config from repo default on first run
if [ ! -f /data/.pi/mcp.json ]; then
cp /app/.pi/mcp.json /data/.pi/mcp.json
fi
# ... QMD collection registration ...
exec node dist/main.js /data
Sources: entrypoint.sh:1-60
Environment Variables and Secrets
Key configuration is passed to the container via AWS Secrets Manager.
| Variable | Source | Purpose |
|---|---|---|
MOM_SLACK_APP_TOKEN | Secret: pi-digby/env | Slack App-level token for Socket Mode. |
MOM_SLACK_BOT_TOKEN | Secret: pi-digby/env | Slack Bot OAuth token. |
CLOUDFLARE_TUNNEL_TOKEN | Secret: pi-digby/env | (Optional) Token for Cloudflare Tunnel egress. |
Sources: deploy/cloudformation.yml:360-385, src/main.ts:25-35
Backup and Retention
The deployment includes automated data protection for the persistent EFS volume.
- AWS Backup: A daily backup plan (
pi-digby-daily) creates snapshots of the EFS file system. - Retention: Backups are retained for 5 days.
- Logs: CloudWatch logs are retained for 30 days.
Sources: deploy/cloudformation.yml:422-455, deploy/cloudformation.yml:178-183
The AWS ECS Fargate deployment provides a robust, production-ready environment for pi-digby. By combining serverless compute with persistent EFS storage and OIDC-based CI/CD, the system maintains high security and operational simplicity while ensuring the AI agent retains context across lifecycles.