deploy-stack 0.18.0 → 0.18.2

package/apps/docs/.astro/dev.json

@@ -0,0 +1,14 @@
+{
+	"pid": 73969,
+	"port": 4321,
+	"url": "http://localhost:4321",
+	"urls": {
+		"local": [
+			"http://localhost:4321/"
+		],
+		"network": [],
+		"networkInterfaceNames": []
+	},
+	"background": false,
+	"startedAt": "2026-09-20T19:07:45.615Z"
+}

package/apps/docs/.astro/settings.json

@@ -0,0 +1,5 @@
+{
+	"_variables": {
+		"lastUpdateCheck": 1789924675360
+	}
+}

package/apps/docs/.astro/types.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="astro/client" />
+/// <reference path="content.d.ts" />

package/apps/docs/astro.config.mjs

@@ -0,0 +1,68 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+// https://starlight.astro.build/reference/configuration/
+export default defineConfig({
+  site: 'https://anton-codes-iac.github.io',
+  base: '/deploy-stack',
+  integrations: [
+    starlight({
+      title: 'deploy-stack',
+      description: 'Provision production-ready AWS infrastructure and CI/CD pipelines in seconds.',
+      customCss: ['./src/custom.css'],
+      sidebar: [
+        {
+          label: 'CLI Commands',
+          items: [
+            { label: 'npx deploy-stack (init)', link: '/cli/init/' },
+            { label: 'apply', link: '/cli/apply/' },
+            { label: 'destroy', link: '/cli/destroy/' },
+            { label: 'secrets push', link: '/cli/secrets/' },
+            { label: 'diagnose', link: '/cli/diagnose/' },
+            { label: 'doctor', link: '/cli/doctor/' },
+            { label: 'eject', link: '/cli/eject/' },
+            { label: 'sync-ai', link: '/cli/sync-ai/' },
+          ],
+        },
+        {
+          label: 'Deployment Guides',
+          items: [
+            { label: 'CI/CD Pipeline & First Deploy', link: '/guides/cicd-pipeline/' },
+            { label: 'Supported Frameworks', link: '/guides/frameworks/' },
+            { label: 'Examples', link: '/guides/examples/' },
+            { label: 'AWS Credentials & Auth', link: '/guides/aws-credentials/' },
+            { label: 'Database Connections', link: '/guides/database-connections/' },
+            { label: 'Secrets Management', link: '/guides/secrets-management/' },
+            { label: 'Dockerfiles & Containers', link: '/guides/dockerfiles/' },
+            { label: 'Docker Compose', link: '/guides/docker-compose/' },
+            { label: 'Ephemeral PR Previews', link: '/guides/ephemeral-pr-previews/' },
+            { label: 'Headless Mode & Automation', link: '/guides/headless/' },
+            { label: 'Re-running Init', link: '/guides/rerun-init/' },
+          ],
+        },
+        {
+          label: 'Platform Migrations',
+          items: [
+            { label: 'Vercel (Next.js)', link: '/migrations/nextjs-vercel-to-aws/' },
+            { label: 'Heroku (Procfile)', link: '/migrations/heroku-procfile-to-aws/' },
+            { label: 'Vercel (Astro)', link: '/migrations/astro-vercel-to-aws/' },
+            { label: 'Vercel (SvelteKit)', link: '/migrations/sveltekit-vercel-to-aws/' },
+          ],
+        },
+        {
+          label: 'Project Details',
+          items: [
+            { label: 'Roadmap', link: '/roadmap/' },
+            { label: 'Testing Strategy', link: '/testing-strategy/' },
+          ],
+        },
+        {
+          label: 'Architecture (ADRs)',
+          items: [
+            { autogenerate: { directory: 'adrs' } }
+          ],
+        },
+      ],
+    }),
+  ],
+});

package/apps/docs/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "docs",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.42.2",
+    "astro": "^7.3.3",
+    "js-yaml": "^4.3.2",
+    "sharp": "^0.34.2"
+  }
+}

package/{docs/adr → apps/docs/src/content/docs/adrs}/0001-s3-native-state-locking.md

@@ -1,4 +1,7 @@
-# 0001. S3 Native State Locking
+---
+title: "S3 Native State Locking"
+description: "When deploying infrastructure via Terraform across local developer workstations and automated CI/CD pipelines, remote state management is required to prevent ra"
+---
 
 * **Status:** Accepted
 * **Date:** 2026-08-15 (Retroactive)

package/{docs/adr → apps/docs/src/content/docs/adrs}/0002-eject-mechanism-pure-iac.md

@@ -1,4 +1,7 @@
-# 0002. Eject Mechanism for Pure IaC
+---
+title: "Eject Mechanism for Pure IaC"
+description: "deploy-stack abstracts away the complexity of writing raw Terraform for ECS Fargate, ALBs, CloudFront, OIDC, and Secrets Manager. However, a primary reason seni"
+---
 
 * **Status:** Accepted
 * **Date:** 2026-08-20 (Retroactive)

package/{docs/adr → apps/docs/src/content/docs/adrs}/0003-sync-ai-context-strategy.md

@@ -1,4 +1,7 @@
-# 0003. AI Context Synchronization Strategy
+---
+title: "AI Context Synchronization Strategy"
+description: "Modern engineering teams heavily utilize AI coding assistants (Cursor, GitHub Copilot, Windsurf, Claude Code, etc.) in their local IDEs. However, when dealing w"
+---
 
 * **Status:** Accepted
 * **Date:** 2026-09-02 (Retroactive)

package/{docs/adr → apps/docs/src/content/docs/adrs}/0004-iac-driven-diagnostic-context.md

@@ -1,4 +1,7 @@
-# 0004. IaC-Driven Diagnostic Context (Stateless CLI)
+---
+title: "IaC-Driven Diagnostic Context (Stateless CLI)"
+description: "To provide a seamless developer experience, the deploy-stack diagnose command needs to automatically fetch CloudWatch logs and ECS task failures without requiri"
+---
 
 * **Status:** Accepted
 * **Date:** 2026-09-19

package/apps/docs/src/content/docs/cli/apply.md

@@ -0,0 +1,29 @@
+---
+title: apply
+description: Provision or update your AWS infrastructure with Terraform.
+---
+
+Run the Terraform plan/apply flow against the generated configuration.
+
+## What it does
+
+- Verifies you are in a deploy-stack project (`terraform/main.tf` must exist), exiting otherwise, so `apply` never runs against the wrong directory.
+- Renders an infrastructure preview from your Terraform config and framework detection. With `--dry-run` it stops there and provisions nothing.
+- Otherwise runs `terraform init -upgrade` followed by `terraform apply -auto-approve` in `terraform/`, streaming progress, then prints the live URLs from the Terraform outputs (`cloudfront_url` and `alb_direct_url`) plus the `git push` command that deploys your app and clears the initial 503.
+- On the known GitHub OIDC provider conflict (`EntityAlreadyExists` for `token.actions.githubusercontent.com`), tells you to set `create_oidc_provider = false` in `terraform/oidc.tf` and re-run; other failures print the Terraform error and the manual `cd terraform && terraform apply` fallback.
+- Emits an `infrastructure_applied` telemetry event recording success or the error code.
+
+## Usage
+
+```bash
+npx deploy-stack apply
+npx deploy-stack apply --dry-run
+```
+
+## Flags
+
+| Flag | Description |
+| ---- | ----------- |
+| `--dry-run` | Render a preview of the planned changes without applying them. |
+
+`apply` shells out to the `terraform` binary in your generated `terraform/` directory and streams progress while it runs.

package/apps/docs/src/content/docs/cli/destroy.md

@@ -0,0 +1,29 @@
+---
+title: destroy
+description: Tear down all AWS resources provisioned for this project.
+---
+
+Permanently delete the AWS infrastructure created by `apply` when a project is retired or needs a clean rebuild, protecting you from ongoing AWS charges.
+
+## What it does
+
+- Verifies you are in a deploy-stack project (`terraform/backend.tf` must exist) and that the `terraform` binary is installed, exiting otherwise.
+- Asks for explicit confirmation before doing anything destructive; declining cancels with no changes.
+- Runs `terraform destroy -auto-approve` in `terraform/`, streaming progress, so all compute resources (ECS, ALB, database, and related resources) are removed.
+- Parses the state bucket name and region out of `terraform/backend.tf` (region defaults to `us-east-2` when not found), then optionally asks whether to also empty and delete the S3 state bucket via `teardownStateBucket`. Answering "No" keeps the bucket so `apply` can restore the infrastructure later.
+- Emits an `infrastructure_destroyed` telemetry event recording success and whether the state bucket was retained.
+
+## Usage
+
+```bash
+npx deploy-stack destroy
+```
+
+## Flags
+
+This command accepts no CLI flags. Both confirmation prompts are interactive.
+
+## See also
+
+- [apply](/cli/apply/)
+- [doctor](/cli/doctor/)

package/apps/docs/src/content/docs/cli/diagnose.md

@@ -0,0 +1,28 @@
+---
+title: diagnose
+description: Diagnose failing ECS deployments from logs and task state.
+---
+
+Inspect recent ECS task failures and CloudWatch logs for the current project.
+
+## What it does
+
+- Saves you from digging through the AWS console by finding the most recently stopped ECS task for this project and showing why it stopped plus the failing container's recent log events (up to 50 lines).
+- Resolves its inputs automatically: the AWS region from `region` in `terraform/main.tf` (default `us-east-1`), overridable via `AWS_REGION`; the cluster (`<project-name>-cluster`, overridable via `ECS_CLUSTER`); and the log group (`/ecs/<project-name>`, overridable via `ECS_LOG_GROUP`).
+- Lists up to 10 recent stopped tasks, describes up to 5 of them, and diagnoses the most recently stopped one: stopped reason, failing container name, exit code, and container reason.
+- Makes no changes to your infrastructure; it is read-only. Prints a healthy message and exits when no stopped tasks exist.
+- On expired AWS credentials, points you to `aws sso login` / `aws configure` and the [AWS credentials guide](/guides/aws-credentials/).
+- Emits a `diagnose_run` telemetry event recording success and whether the service was healthy.
+
+## Usage
+
+```bash
+npx deploy-stack diagnose
+npx deploy-stack wtf
+```
+
+`wtf` is an alias for `diagnose`.
+
+## Flags
+
+This command accepts no CLI flags. Region, cluster, and log group are resolved as described above, not from flags.

package/apps/docs/src/content/docs/cli/doctor.md

@@ -0,0 +1,28 @@
+---
+title: doctor
+description: Check that required tools are installed before provisioning.
+---
+
+Verify your machine is ready to provision and deploy, telling you exactly which dependency to install when something is missing.
+
+## What it does
+
+- Checks for the four required binaries — `terraform`, `aws` (AWS CLI), `docker`, and `git` — and prints a pass/fail line for each with a Homebrew install hint for anything missing.
+- Makes no changes to your project or cloud resources; it is a read-only check.
+- Prints a success message when everything is present, or a reminder to install the missing dependencies first.
+- Emits a `doctor_run` telemetry event recording whether all checks passed.
+
+## Usage
+
+```bash
+npx deploy-stack doctor
+```
+
+## Flags
+
+This command accepts no CLI flags.
+
+## See also
+
+- [npx deploy-stack (init)](/cli/init/)
+- [apply](/cli/apply/)

package/apps/docs/src/content/docs/cli/eject.md

@@ -0,0 +1,29 @@
+---
+title: eject
+description: Decouple your project from deploy-stack into vanilla Terraform.
+---
+
+Take permanent, sole ownership of your infrastructure files when you no longer want the CLI managing them, while keeping everything running in AWS.
+
+## What it does
+
+- Asks for explicit confirmation (defaulting to "No"); declining cancels with no changes.
+- Strips deploy-stack metadata from your local files: removes the `# deploy-stack generated infrastructure` header and the `default_tags { tags = { ManagedBy = "deploy-stack" } }` block from `terraform/main.tf`, and removes the `# deploy-stack backups` block from `.gitignore`.
+- Recursively deletes every `*.bak.*` backup file in the project (skipping `node_modules` and `.git`).
+- Leaves your infrastructure fully operational as raw, standalone Terraform. As a final step, run `terraform apply` inside `terraform/` so AWS syncs state and removes the live `ManagedBy` tags.
+- Emits a `project_ejected` telemetry event. This cannot be undone.
+
+## Usage
+
+```bash
+npx deploy-stack eject
+```
+
+## Flags
+
+This command accepts no CLI flags. The confirmation prompt is interactive.
+
+## See also
+
+- [apply](/cli/apply/)
+- [destroy](/cli/destroy/)

package/apps/docs/src/content/docs/cli/init.md

@@ -0,0 +1,42 @@
+---
+title: Initializing Project (npx deploy-stack)
+description: Scaffold production-ready AWS infrastructure and CI/CD pipelines.
+---
+
+Generate Terraform, Docker, and GitHub Actions files for your project.
+
+## What it does
+
+- Turns your codebase into a deployable AWS project: auto-detects your framework, `Procfile`, `vercel.json`, and `docker-compose.yml`, warns about framework-specific migration issues (NestJS bind address, Next.js standalone output, SvelteKit/Astro adapters), then provisions the remote-state S3 bucket and synthesizes Terraform, Docker, and CI/CD files.
+- Backs up any existing generated files before overwriting them, and writes AI assistant rule files for the assistants you choose (advanced mode) or the ones already present in your repo (quickstart mode).
+- Finishes with the exact next steps: the `apply` command to provision, and the `git` commands to commit and push.
+- Emits `project_provisioned` and `cli-error` telemetry events (disable with `--no-telemetry`).
+
+## Usage
+
+```bash
+npx deploy-stack
+npx deploy-stack --headless --framework=nextjs --region=us-east-2
+```
+
+Running with no subcommand starts the interactive setup wizard (`init` is the default command).
+
+## Headless flags
+
+| Flag | Description |
+| ---- | ----------- |
+| `--headless` | Bypass all interactive prompts (for CI/CD and automation). |
+| `--framework=<name>` | `node`, `nextjs`, `nuxt`, `python`, `django`, `rails`, `go`, `static`. |
+| `--region=<region>` | AWS region (e.g. `us-east-1`). |
+| `--port=<port>` | Container port your app listens on. |
+| `--size=<size>` | Fargate task size preset. |
+| `--healthCheckPath=<path>` | ALB health-check path. |
+| `--desiredCount=<n>` | Number of tasks to run. |
+| `--branch=<name>` | Branch the CI workflow deploys. |
+| `--needsDatabase` | Provision a managed database. |
+| `--enablePrPreviews` | Enable ephemeral PR preview environments. |
+| `--dir=<path>` | Target directory for generated files. |
+| `--preconfigured` | Skip framework-specific warnings (for preconfigured setups). |
+| `--no-telemetry` | Disable telemetry for this run. |
+
+See the [Headless Mode guide](/guides/headless/) for automation examples.

package/apps/docs/src/content/docs/cli/secrets.md

@@ -0,0 +1,36 @@
+---
+title: secrets push
+description: Push local environment variables to AWS Secrets Manager.
+---
+
+Upload your `.env` file to the Secrets Manager vault provisioned for this project, so your deployed app can read the values at runtime.
+
+## What it does
+
+- Reads and parses a local env file (defaults to `.env`) and pushes every key as a single JSON secret string to the `<project-name>-secrets` vault via `UpdateSecretCommand`. This is the value of the command: no manual AWS console edits, and your app picks up the values on the next deployment.
+- Resolves the AWS region from the `region` setting in `terraform/main.tf`, falling back to `AWS_REGION` or your AWS profile default.
+- Writes the pushed key names to `terraform/secret_keys.json` so the Terraform configuration and CI redeploy know which variables exist. Commit this file and push to trigger a deployment with the new variables.
+- Emits a `secrets_pushed` telemetry event. Exits non-zero on failure.
+
+## Usage
+
+```bash
+npx deploy-stack secrets push
+npx deploy-stack secrets push .env.production
+```
+
+The optional positional argument is the path of the env file to push (resolved relative to the project root). It defaults to `.env` when omitted or blank.
+
+## Flags
+
+This command accepts no CLI flags.
+
+## Prerequisites
+
+- Run `npx deploy-stack apply` first: the `<project-name>-secrets` vault is created during provisioning. If it does not exist yet, the command points you back to `apply`.
+- Valid AWS credentials. On expired credentials, refresh with `aws sso login` or `aws configure`. See the [AWS credentials guide](/guides/aws-credentials/).
+
+## See also
+
+- [Secrets management guide](/guides/secrets-management/)
+- [apply](/cli/apply/)

package/apps/docs/src/content/docs/cli/sync-ai.md

@@ -0,0 +1,27 @@
+---
+title: sync-ai
+description: Regenerate AI assistant rules for an existing project.
+---
+
+Give your AI coding assistants up-to-date deploy-stack context after project settings change, so they generate correct Terraform and deployment instructions instead of hallucinating them.
+
+## What it does
+
+- Prompts you to choose which AI assistants to configure, then writes the matching rule files with your project's region (from `region` in `terraform/main.tf`) and container port (from `containerPort` in `terraform/main.tf`).
+- Writes a full rule file for Cursor (`.cursor/rules/deploy-stack.mdc`), Roo (`.roo/rules/deploy-stack.md`), Trae (`.trae/rules/project_rules.md`), and Continue (`.prompts/deploy-stack.prompt`); injects a managed block into the existing config for Windsurf (`.windsurfrules`), Copilot (`.github/copilot-instructions.md`), Claude (`CLAUDE.md`), Goose (`.goosehints`), and Aider (`.aider.conf.yml`).
+- Exits without writing anything when no assistants are selected.
+- Emits a `sync_ai_executed` telemetry event listing the selected assistants.
+
+## Usage
+
+```bash
+npx deploy-stack sync-ai
+```
+
+## Flags
+
+This command accepts no CLI flags. Assistant selection is interactive.
+
+## See also
+
+- [npx deploy-stack (init)](/cli/init/)

package/apps/docs/src/content/docs/guides/aws-credentials.md

@@ -0,0 +1,68 @@
+---
+title: Troubleshooting AWS Credentials & Authentication
+description: Troubleshooting AWS authentication, expired tokens, and SSO logins.
+---
+
+`deploy-stack` interacts directly with AWS APIs (Secrets Manager, ECS, CloudWatch, S3) using the official AWS SDK v3 default credential provider chain.
+
+When you encounter an `UnrecognizedClientException` or `ExpiredTokenException`, your local AWS authentication state has lapsed.
+
+---
+
+## 1. Quick Refresh by Setup Type
+
+### A. AWS IAM Identity Center (AWS SSO)
+If your organization or personal account uses IAM Identity Center / SSO:
+
+```bash
+# Log in to refresh your active session token
+aws sso login
+```
+
+If you use named profiles:
+```bash
+aws sso login --profile your-profile-name
+export AWS_PROFILE=your-profile-name
+```
+
+---
+
+### B. Standard Long-Lived Access Keys (`~/.aws/credentials`)
+If you use long-lived `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` pairs:
+
+1. Verify credentials configured:
+   ```bash
+   aws sts get-caller-identity
+   ```
+2. If invalid or missing:
+   ```bash
+   aws configure
+   ```
+
+---
+
+### C. Temporary Session Tokens (`AWS_SESSION_TOKEN`)
+If you assumed an IAM role or exported manual session tokens in your terminal:
+
+Check if stale environment variables are overriding your global credentials:
+```bash
+echo $AWS_SESSION_TOKEN
+```
+If expired, clear them:
+```bash
+unset AWS_ACCESS_KEY_ID
+unset AWS_SECRET_ACCESS_KEY
+unset AWS_SESSION_TOKEN
+```
+Then re-authenticate via `aws configure` or `aws sso login`.
+
+---
+
+## 2. Common Error References
+
+| Error Name | Root Cause | Solution |
+| :--- | :--- | :--- |
+| `UnrecognizedClientException` | The security token is unrecognized, mistyped, or expired. | Run `aws sso login` or re-run `aws configure`. |
+| `ExpiredTokenException` | Temporary STS credentials passed their validity window (typically 1–12 hrs). | Refresh STS credentials or log into SSO again. |
+| `AccessDeniedException` | User or role lacks IAM permissions for ECS, Secrets Manager, or S3. | Ensure your IAM user has adequate deployment permissions. |
+| `ResourceNotFoundException` | Target cluster, secret, or log group does not exist in target region. | Verify `AWS_REGION` and ensure infrastructure was provisioned via `deploy-stack apply`. |

package/apps/docs/src/content/docs/guides/cicd-pipeline.md

@@ -0,0 +1,46 @@
+---
+title: CI/CD Pipeline & First Deploy
+description: How the generated GitHub Actions workflow builds, scans, and deploys your app with zero stored AWS keys.
+sidebar:
+  order: 1
+---
+
+Every `npx deploy-stack` run generates `.github/workflows/deploy.yml`. This page explains what that pipeline does, when it runs, and why your site returns `503` until the first push completes.
+
+## When it runs
+
+The workflow triggers on two events (`templates/github/deploy.yml`):
+
+- A `push` to your deploy branch (`{{DEPLOY_BRANCH}}`, chosen during setup).
+- A weekly Sunday cron (`0 0 * * 0`) that re-applies the Terraform configuration, so drift and base-image updates converge automatically.
+
+The region, ECR repository, ECS cluster, and ECS service names are baked in at generation time as `<project>-repo`, `<project>-cluster`, and `<project>-service`.
+
+## No stored AWS keys
+
+Authentication uses GitHub OIDC, not long-lived credentials. The workflow declares:
+
+```yaml
+permissions:
+  id-token: write
+  contents: read
+```
+
+and assumes the `{{PROJECT_NAME}}-github-actions-role` IAM role created by `terraform/oidc.tf`. There is nothing to rotate and no secret to leak. (If your AWS account already has a GitHub OIDC provider, set `create_oidc_provider = false` in `terraform/oidc.tf` — see [apply](/cli/apply/).)
+
+## The five stages
+
+1. **IaC security scan.** Trivy scans `terraform/` for vulnerabilities, secrets, and misconfigurations (`CRITICAL,HIGH`). It is informational only (`exit-code: '0'`), so it never blocks the build; results land in the GitHub step summary.
+2. **Infrastructure sync.** The `anton-codes-iac/deploy-stack-action@v1` step runs Terraform against `terraform/`, so infrastructure changes committed alongside code are applied before the new image rolls out.
+3. **Build & push.** The workflow logs in to Amazon ECR, runs `docker build` on your generated `Dockerfile`, and tags the result `latest`.
+4. **Container scan.** Trivy scans the built image (`os,library`, `ignore-unfixed: true`), again informational only with results in the step summary.
+5. **Deploy.** The image is pushed to ECR and the workflow forces a new ECS deployment (`aws ecs update-service --force-new-deployment`), which rolls the new image across your tasks behind the ALB.
+
+## Why you see a 503 first
+
+`npx deploy-stack apply` provisions the ALB, cluster, and service, but no container image exists until this workflow runs once. Pushing to your deploy branch (`git add . && git commit -m "ci: infra" && git push`) builds and deploys the first image, clearing the `503`. If the service stays unhealthy after that, run `npx deploy-stack diagnose` — usually the container failed its ALB health check (see [Dockerfiles](/guides/dockerfiles/)).
+
+## Related workflows
+
+- `preview.yml` / `teardown.yml` exist only when ephemeral PR previews are enabled. See [Ephemeral PR Previews](/guides/ephemeral-pr-previews/).
+- Secrets are injected at deploy time from AWS Secrets Manager, never from the repo. See [Secrets Management](/guides/secrets-management/).

package/{docs → apps/docs/src/content/docs}/guides/database-connections.md

@@ -1,4 +1,7 @@
-# Managed Database Connections
+---
+title: "Managed Database Connections"
+description: "When you run npx deploy-stack for a backend framework (Node, Django, Rails, Go, etc.), the CLI prompts you to automatically provision a managed AWS RDS PostgreS"
+---
 
 When you run `npx deploy-stack` for a backend framework (Node, Django, Rails, Go, etc.), the CLI prompts you to automatically provision a managed AWS RDS PostgreSQL database.
 

package/apps/docs/src/content/docs/guides/docker-compose.md

@@ -0,0 +1,37 @@
+---
+title: Docker Compose Support
+description: How deploy-stack maps docker-compose.yml services to ECS — web-service selection, ports, env vars, and sidecars.
+sidebar:
+  order: 4
+---
+
+If your repo contains a `docker-compose.yml` (or `docker-compose.yaml`), setup parses it (`src/utils/dockerCompose.js`) and translates its services into the ECS task definition. Your Compose file keeps working locally, and these are the exact mapping rules that decide what runs in AWS.
+
+## File discovery
+
+Only the repo root is checked, trying `docker-compose.yml` first and then `docker-compose.yaml`. A file with no `services` key — or one that fails YAML parsing — is treated as absent (a warning is printed, setup continues), so a stray or malformed file never blocks generation.
+
+## Which service is "web"
+
+The service used as the ECS web service is the **first service with an exposed port**; if none exposes a port, the first service listed wins. Every other service becomes an ECS **sidecar** in the same task definition. Structure your file accordingly: the publicly reachable app must be the port-exposing service.
+
+## Port mapping
+
+The container port is taken from the **last segment of the first port entry** — `"8080:80"` and `"127.0.0.1:8001:8001"` both resolve to the right-hand value (`80` and `8001`). Only the first entry is read, and any non-numeric characters are stripped. This port overrides the configured container port during setup, and the ALB health check targets it.
+
+## Environment and command injection
+
+- **Environment** supports both Compose styles: `environment:` as a mapping is used as-is; as a list (`- KEY=value`) each entry is split on the first `=`.
+- The web service's variables are injected directly into the ECS task definition, and its `command` overrides the container start command — but only when no `Procfile` `web:` process already set one (`Procfile` wins; see [Dockerfiles](/guides/dockerfiles/)).
+- Sidecars get the same treatment: their environment is injected, their `command` is preserved, a missing `image` defaults to `alpine:latest`, and each sidecar logs to the shared CloudWatch log group under an `ecs-<service>` stream prefix.
+
+## What this means in practice
+
+- Sidecars (Redis, Memcached, background helpers) run **in the same task** as the web container and share its lifecycle — this is co-location, not separate services.
+- Compose `build:` contexts are not used in AWS; the image is built from the generated `Dockerfile` by the [CI/CD pipeline](/guides/cicd-pipeline/).
+- Runtime secrets still belong in AWS Secrets Manager, not in Compose `environment:`. See [Secrets Management](/guides/secrets-management/).
+
+## See also
+
+- [Supported Frameworks](/guides/frameworks/) for detection and defaults.
+- [Dockerfiles & the container contract](/guides/dockerfiles/) for runtime requirements.

package/apps/docs/src/content/docs/guides/dockerfiles.md

@@ -0,0 +1,46 @@
+---
+title: Dockerfiles & the Container Contract
+description: What your app must do at runtime (port, bind address, health check) and the per-framework prerequisites.
+sidebar:
+  order: 3
+---
+
+Setup generates a framework-specific Alpine multi-stage `Dockerfile` engineered for zero Critical/High CVEs. Your app only needs to honor a small runtime contract — plus a few per-framework prerequisites printed as warnings (`src/utils/warnings.js`) at the end of setup.
+
+## The container contract
+
+Every generated image assumes three things. Violating any of them is the most common cause of failing ALB health checks after an otherwise successful `apply`:
+
+1. **Listen on `$PORT`.** The container must serve traffic on the port baked in as `{{PORT}}` (default per framework — see [Supported Frameworks](/guides/frameworks/)).
+2. **Bind `0.0.0.0`, not `localhost`.** Localhost-bound apps are unreachable inside ECS networking and Docker.
+3. **Answer the health check with `200 OK`.** The ALB polls your health-check path (default `/`); anything else marks the task unhealthy and the pipeline's new deployment never stabilizes.
+
+## Per-framework prerequisites
+
+| Framework | What setup warns you about |
+| --------- | -------------------------- |
+| NestJS | Bind `0.0.0.0` in `src/main.ts`: `await app.listen(process.env.PORT ?? 3000, '0.0.0.0')` |
+| Next.js | Set `output: 'standalone'` in your Next config and create a health-check route (copy-paste code is in the generated README's "Critical Application Prerequisites") |
+| Node.js / Express | A `start` script in `package.json` (e.g. `"start": "node index.js"`) and `0.0.0.0` binding |
+| Python (FastAPI) | Web framework in `requirements.txt`, `0.0.0.0` binding, and a health-check route returning `200 OK` |
+| Rails | Your default `Dockerfile` is backed up to `Dockerfile.bak` and replaced with the Alpine build; if you use SQLite locally but provisioned RDS, add the `pg` gem |
+| Static sites | Output folder defaults to `/app/dist` — if your framework emits `build/` or `out/`, update the `COPY` command; ensure a `build` script exists (e.g. `vite build`) |
+
+Warnings are skipped with `--preconfigured` and for `static` projects whose build directory was auto-detected.
+
+## What command runs your app
+
+The container's start command is resolved in this order:
+
+1. `Procfile` `web:` command, if a `Procfile` exists (a `worker:` process additionally generates `worker.tf`, i.e. a second ECS service that doubles Fargate cost).
+2. Otherwise the `command` of the `docker-compose.yml` web service, if one exists.
+3. Otherwise the default `CMD` in the generated `Dockerfile`.
+
+## Keeping images lean
+
+Setup writes a `.dockerignore` excluding `.git/`, `terraform/`, state files, and `.env`, and appends Terraform entries to an existing `.gitignore`. Never commit `.env` — runtime secrets come from AWS Secrets Manager (see [Secrets Management](/guides/secrets-management/)).
+
+## See also
+
+- [CI/CD Pipeline & First Deploy](/guides/cicd-pipeline/) for how the image is built and rolled out.
+- [diagnose](/cli/diagnose/) for reading ECS failure output when the contract is broken.

package/{docs → apps/docs/src/content/docs}/guides/ephemeral-pr-previews.md

@@ -1,4 +1,7 @@
-# 🚀 Ephemeral PR Previews
+---
+title: "Ephemeral PR Previews"
+description: "When enabled, deploy-stack automatically configures your GitHub Actions pipeline to spin up isolated, temporary AWS environments every time a developer opens a "
+---
 
 When enabled, `deploy-stack` automatically configures your GitHub Actions pipeline to spin up isolated, temporary AWS environments every time a developer opens a Pull Request.