paperclip/docker/.env.aws.example

# AWS ECS Fargate deployment environment
# Copy to .env.aws and fill in values before deploying
#
# Secrets (DATABASE_URL, BETTER_AUTH_SECRET, ANTHROPIC_API_KEY, OPENAI_API_KEY,
# GITHUB_TOKEN) are injected via AWS Secrets Manager — do NOT set them here.

# Deployment mode
PAPERCLIP_DEPLOYMENT_MODE=authenticated
PAPERCLIP_DEPLOYMENT_EXPOSURE=public
PAPERCLIP_PUBLIC_URL=https://paperclip.example.com

# Server
HOST=0.0.0.0
PORT=3100
NODE_ENV=production
SERVE_UI=true

# Paperclip paths
PAPERCLIP_HOME=/paperclip
PAPERCLIP_INSTANCE_ID=default
PAPERCLIP_CONFIG=/paperclip/instances/default/config.json

# Auto-apply migrations on startup
PAPERCLIP_MIGRATION_AUTO_APPLY=true

# Enable heartbeat scheduler for remote agents
HEARTBEAT_SCHEDULER_ENABLED=true

# Post-deploy hardening (uncomment after first user signs up)
# PAPERCLIP_AUTH_DISABLE_SIGN_UP=true
docs: AWS ECS Fargate deployment runbook (#3897) ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies and ships a > "local-first, cloud-ready" deployment model > - The deploy docs currently cover local/Docker but not a production > cloud target, so teams asking "how do I put this behind a real domain" > have no canonical path > - We already support Docker images, RDS-compatible Postgres, and an EFS > storage profile, so AWS ECS Fargate is a natural fit > - Without a runbook, each team reinvents VPC, security groups, TLS, and > secrets wiring and usually gets at least one step wrong > - This pull request adds `docs/deploy/aws-ecs.md`, an ECS task-definition > template, and an `.env.aws.example`, cross-linked from the deploy overview > - The benefit is a single, reproducible ~$110/mo path to a production > deployment, plus a full teardown for throwaway environments ## What Changed - New `docs/deploy/aws-ecs.md` — an 11-step ECS Fargate runbook covering ECR, VPC, RDS, EFS, Secrets Manager, IAM, ALB, and ECS service with the deployment circuit breaker enabled - New `docker/ecs-task-definition.json` — Fargate-ready task definition with `<ACCOUNT_ID>`, `<REGION>`, `<EFS_ID>`, `<DOMAIN>` placeholder tokens - New `docker/.env.aws.example` — documents every non-secret env var the ECS deployment needs - `docs/deploy/overview.md` — one-line cross-reference to the new guide - Greptile feedback addressed in follow-up commits: - `containerName` in the service-create call now matches `paperclip-server` in the task definition - HTTP :80 listener added that 301-redirects to :443 - Dedicated RDS DB subnet group created before `create-db-instance` - EFS teardown polls on mount-target deletion instead of `sleep 30` ## Verification - Walked every step of the runbook against the task definition to confirm variable names (`$ALB_SG`, `$ECS_SG`, `$RDS_SG`, `$EFS_SG`, `$TG_ARN`, `$LISTENER_ARN`, `$HTTP_LISTENER_ARN`, `$EFS_ID`, `$RDS_ENDPOINT`, etc.) are defined before they are referenced - Confirmed the `containerName` in Step 10 (`paperclip-server`) matches `docker/ecs-task-definition.json` line 11 - Confirmed the `sed` placeholder substitution in Step 8 matches the tokens in the task definition template - Teardown order was checked in reverse-dependency order: ECS service → listeners → target group → ALB → RDS (waits for deletion) → DB subnet group → EFS mount targets (polled) → EFS → secrets → SGs → ECR → IAM → log group ## Risks - Low risk for the repo. Docs-only change plus two template files under `docker/`; no runtime code paths are touched and nothing is imported by the build. - Risk for users who follow the runbook: AWS bills accrue immediately once RDS/ALB/EFS exist. The runbook calls this out and includes a full teardown procedure. Placeholder tokens (`<ACCOUNT_ID>`, `<REGION>`, `<EFS_ID>`, `<DOMAIN>`) are documented so nothing is silently hard-coded. ## Model Used - Claude (Anthropic), model `claude-opus-4-6`, ~200K context window, extended thinking mode on, used with tool access (file edit, shell) via Claude Code. The Greptile follow-up commits were authored the same way. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have run tests locally and they pass — N/A for docs/config templates; validated by reading - [x] I have added or updated tests where applicable — N/A for docs - [x] If this change affects the UI, I have included before/after screenshots — N/A, no UI - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> 2026-04-27 06:41:47 -07:00			`# AWS ECS Fargate deployment environment`
			`# Copy to .env.aws and fill in values before deploying`
			`#`
			`# Secrets (DATABASE_URL, BETTER_AUTH_SECRET, ANTHROPIC_API_KEY, OPENAI_API_KEY,`
			`# GITHUB_TOKEN) are injected via AWS Secrets Manager — do NOT set them here.`

			`# Deployment mode`
			`PAPERCLIP_DEPLOYMENT_MODE=authenticated`
			`PAPERCLIP_DEPLOYMENT_EXPOSURE=public`
			`PAPERCLIP_PUBLIC_URL=https://paperclip.example.com`

			`# Server`
			`HOST=0.0.0.0`
			`PORT=3100`
			`NODE_ENV=production`
			`SERVE_UI=true`

			`# Paperclip paths`
			`PAPERCLIP_HOME=/paperclip`
			`PAPERCLIP_INSTANCE_ID=default`
			`PAPERCLIP_CONFIG=/paperclip/instances/default/config.json`

			`# Auto-apply migrations on startup`
			`PAPERCLIP_MIGRATION_AUTO_APPLY=true`

			`# Enable heartbeat scheduler for remote agents`
			`HEARTBEAT_SCHEDULER_ENABLED=true`

			`# Post-deploy hardening (uncomment after first user signs up)`
			`# PAPERCLIP_AUTH_DISABLE_SIGN_UP=true`