deploy-stack ☁️🚀

The zero-lock-in cloud generator. Eject your containerized web app from expensive PaaS platforms to production-ready, highly available AWS infrastructure in 60 seconds.

---

The Problem

Managed platforms like Vercel, Heroku, or Render offer rapid initial deployments, but costs escalate quickly with seat pricing, compute caps, and bandwidth markups.

Migrating directly to AWS provides greater cost efficiency and infrastructure control. However, architecting raw Terraform for ECS clusters, Application Load Balancers, CloudFront distributions, and keyless CI/CD pipelines typically requires writing hundreds of lines of complex boilerplate infrastructure code.

The Solution

deploy-stack is an interactive CLI that streamlines the process. It analyzes your project requirements and generates clean, readable, and completely ejectable Terraform and GitHub Actions workflows directly inside your repository.

You retain complete ownership of your infrastructure code without relying on black-box platforms.

---

✨ Features

🚀 Zero-Config Deployments

• Framework Agnostic: Tailored container presets for 10 supported frameworks — Node.js/Express, NestJS, Next.js, Nuxt 3, SvelteKit, Python/FastAPI, Django, Rails, Go, and Static Sites (React, Vue, Astro).
• Smart Discovery: Automatically detects build output directories and generates highly optimized, multi-stage Dockerfiles.
• Migration Engines: Natively parses Heroku Procfile configurations, vercel.json routing rules, and docker-compose.yml sidecar architectures to automatically translate them into standard AWS Fargate and Application Load Balancer topologies.
• Database Scaffolding: Automatically provisions fully isolated, zero-trust AWS databases for backend monoliths — RDS PostgreSQL 16, RDS MySQL 8.0, or Aurora PostgreSQL Serverless v2 with 0–2 ACU scale-to-zero (--db-engine, or pick interactively with per-engine cost hints).
• Dependency-Aware Init: Scans your manifests for database, worker, migration, and addon signals before prompting — pre-selecting the database question, pre-filling the worker command, pre-checking detected addons with evidence, and offering the migration gate — or compose the stack explicitly with --with in headless mode.

🛡️ DevSecOps & Security

• Automated Trivy Scanning: Integrated IaC and container vulnerability scanning on every GitHub Actions run.
• Continuous IaC Validation: Matrix pipeline scaffolds all 10 supported frameworks headlessly and gates every commit on terraform validate, tflint, and Trivy (HIGH/CRITICAL).
• Hardened Containers: Explicitly drops root privileges using nginx-unprivileged and distroless bases for strict Fargate security compliance.
• Zero-Secret CI/CD: Utilizes AWS IAM OpenID Connect (OIDC) for automated deployments—no long-lived AWS keys in GitHub.
• Built-in Secrets Manager: Push local .env variables into encrypted AWS Secrets Manager vaults, pull them back onto a new machine, and audit local-vs-remote drift — with one-prompt rolling ECS restarts for value-only rotations.

☁️ AWS Native Architecture

• Production Defaults: Provisions an Amazon ECS Fargate cluster fronted by an Application Load Balancer across multiple availability zones.
• Global Edge Acceleration: Integrated AWS CloudFront CDN distribution with SSL termination and edge caching.
• Modular Day-2 Addons: Attach private S3 storage (add storage:s3), serverless DynamoDB (add db:dynamodb), Valkey caching (add db:redis), SQS queues (add queue:sqs), Bedrock AI access (add ai:bedrock), or SES transactional email (add email:ses) anytime after init — no Terraform hand-writing, with container env wiring included — plus scheduled cron jobs (add cron) that run one-off Fargate tasks on an EventBridge schedule.
• Cost & Observability: Keeps AWS spend visible with fixed-baseline cost previews before every provision, explicit 14-day CloudWatch log retention, and auto-generated 5XX error alerting. Pause idle environments with one command (sleep/wake) and see the exact hourly savings, and catch out-of-band console changes with scheduled IaC drift detection (drift).

🛠️ Developer Experience

• Zero Vendor Lock-In: Generates standard, readable Terraform (.tf) files. You own the infrastructure.
• Native S3 State Locking: Automatically creates an encrypted S3 state bucket utilizing modern Terraform concurrency locking.
• Safe Iteration: Idempotent CLI safely backs up existing configurations to .bak files to guarantee zero data loss.
• Ephemeral PR Previews (Opt-In): Automatically spins up completely isolated AWS Fargate environments for every Pull Request and posts the live preview URL to GitHub, accelerating team code reviews.
• 🤖 IDE AI Integration: Automatically generates contextual rules for Cursor, Windsurf, Copilot, and Claude to prevent Terraform hallucinations.

🔭 Day-2 Operations

• Observe & Troubleshoot: Stream CloudWatch logs (logs --tail --error -f), check service health (status, with auto-diagnose on degradation), and open a shell in a running container (exec) — without leaving the terminal.
• Database Lifecycle: Tunnel into your private database (db connect, with mysql:// URIs and Aurora cluster discovery), run migrations inside the VPC (db migrate, auto-detected, or wired into CI with --setup-ci), enable pgvector for AI embeddings (db enable-vector), stream in existing data (db import --file/--from, over a temporary SSM tunnel), and snapshot and restore it (db backup, db restore, cluster-aware for Aurora).
• Cost Control & Safety: Pause idle environments (sleep [env]/wake [env], with exact savings and an RDS auto-restart guard), catch out-of-band console changes (drift, or daily in CI with drift --setup), clean up orphaned resources (gc, dry-run first with explicit confirmation), and roll back to a previous deployment (rollback [revision], with live progress).

---

📚 Documentation & Guides

Transitioning from PaaS to AWS involves a few architectural shifts. Start with our live documentation site for full CLI references, guides, and migration walkthroughs. We've also written concise guides to help you understand how deploy-stack handles the heavy lifting:

• Migrating from Heroku to AWS (Procfile Support)
• Managing Secrets & Environment Variables
• Zero-Trust Database Connections
• Migrating Next.js from Vercel
• Ephemeral PR Previews & AWS Costs

---

🚀 Quick Start

Run the CLI directly in your project root:

npx deploy-stack

The interactive wizard will analyze your codebase, detect your framework, estimate your AWS costs, and generate your Terraform and GitHub Actions configurations.

---

🧰 CLI Command Reference

deploy-stack manages the entire lifecycle of your infrastructure. Each command links to its full reference — flags, examples, and environment overrides.

Command	What it does
apply	Provisions your AWS infrastructure and prints the live URLs (--dry-run previews topology and cost).
secrets push / pull / audit	Encrypts .env files into Secrets Manager, syncs them back, and diffs drift.
doctor	Verifies Docker, Terraform, the AWS CLI, and your generated files.
diagnose (wtf)	Explains a failing ECS deployment from the stopped task and its logs.
logs	Streams CloudWatch logs (--tail, -f, --error, --since).
status	Health dashboard with auto-diagnose on degradation and --json for scripts.
rollback	Returns the live service to a previous task revision, with live progress.
exec	Opens a shell in a running container via Session Manager.
db connect	Opens a localhost tunnel to your private database (PostgreSQL, MySQL, or Aurora).
db migrate	Runs migrations inside the VPC (auto-detected) or installs the CI pre-deploy gate.
db enable-vector	Enables pgvector for AI embeddings with a one-off VPC task.
db import	Streams a local dump or remote database into your private instance over an SSM tunnel.
db backup / db restore	Snapshot checkpoints and Terraform-pinned restores (cluster-aware for Aurora).
gc	Deletes orphaned ECR images, log groups, and EIPs — dry-run first, explicit confirmation only.
sleep / wake	Pauses an environment to $0 compute and restores exact replica counts (--skip-db, --no-wait).
drift	Flags out-of-band AWS changes locally or daily in CI (--setup).
add	Attaches S3, DynamoDB, Redis, SQS, Bedrock, SES, or scheduled cron jobs without writing Terraform.
domain	Attaches a custom domain with automated ACM TLS (Route 53 or external DNS).
destroy	Tears down AWS resources to stop billing (state bucket optionally retained).
eject	Strips deploy-stack metadata, leaving pure Terraform and Actions files.
--headless	Fully programmatic runs for CI/CD (--with, --db-engine, --setup-ci-migrate, --setup-ci-drift).
sync-ai	Generates IDE assistant rules for your stack (Cursor, Copilot, Windsurf, Claude).

---

📁 Generated File Structure

Running the CLI seamlessly integrates a modular, DevSecOps-hardened architecture into your repository:

your-project/
├── Dockerfile                  # Multi-stage container preset
├── .dockerignore               # Prevents secret leaks into container builds
├── .gitignore                  # Automatically updated to ignore tfstate and .bak files
├── .github/
│   └── workflows/
│       ├── deploy.yml          # Keyless OIDC CI/CD deployment pipeline
│       └── drift.yml           # Scheduled IaC drift detection (opt-in via `init --setup-ci-drift` or `drift --setup`)
└── terraform/
    ├── main.tf                 # ECR repository, ECS Cluster, and Fargate Task
    ├── network.tf              # VPC, Public Subnets, ALB, and Security Groups
    ├── cloudfront.tf           # CloudFront CDN edge distribution
    ├── domain.tf               # Custom domain + ACM certificate (via `domain add`, when configured)
    ├── oidc.tf                 # GitHub Actions keyless IAM OIDC Provider & Roles
    ├── secrets.tf              # AWS Secrets Manager integration
    ├── backend.tf              # S3 Remote State backend with native locking
    ├── database.tf             # Managed database — RDS PostgreSQL/MySQL or Aurora Serverless v2 (backend frameworks only)
    ├── worker.tf               # Background worker service (Procfile projects only)
    ├── s3.tf / dynamodb.tf / redis.tf / sqs.tf / bedrock.tf / ses.tf / cron.tf   # Modular addons via `deploy-stack add` (when added)
    └── secret_keys.json        # Dynamic key map for injected environment variables

---

📦 Reference Implementations

• Next.js Fullstack App: A complete Next.js deployment showcasing the generated Terraform, CloudFront setup, and automated OIDC workflow.
• Docker Compose to AWS Migration: Demonstrates automatic translation of local docker-compose.yml sidecars (like Redis) into a multi-container AWS ECS Task Definition communicating over localhost.
• Heroku to AWS Migration (Django): A classic Heroku-style monolith migrated via the Procfile Importer.
• Zero-Secret AWS Secrets Manager Injection: A production-grade Node.js architecture demonstrating zero-plaintext secret injection. Encrypts local .env variables directly into AWS and maps them into ECS memory at container boot, verified against GitHub's API.

👉 View all 14+ reference implementations in our Examples Gallery

---

🤖 AI Context Management (Cursor, Roo Code, Trae, Copilot, Windsurf, Claude, Goose, Aider, Continue)

AI coding assistants are incredible, but they often hallucinate custom Terraform or raw AWS CLI commands that can break your infrastructure state. deploy-stack natively intercepts and guides AI agents directly in your IDE by providing strict deployment rules and project-specific context (like your exact AWS Region and Container Port).

How it works:

• Quickstart Flow: The CLI silently auto-detects if you are using AI tools in your repository and safely injects context.
• Advanced Flow: You are explicitly prompted to choose which AI assistants your team uses.
• Standalone Command: You can run npx deploy-stack sync-ai at any time to selectively generate these rules later.

Safe & Non-Destructive: We use isolated rule files (like .cursor/rules/deploy-stack.mdc) or strictly delimited blocks (``) to ensure your team's existing agent instructions, coding standards, and project prompts are never overwritten.

---

🛡️ Telemetry & Privacy

By default, deploy-stack collects anonymous, hashed usage data to help improve the CLI (e.g., framework presets used, deployment success rates). No codebase files, AWS credentials, or personal data are ever collected.

To opt out, simply append the flag:

npx deploy-stack --no-telemetry

To opt out of every run at once, set DO_NOT_TRACK=1 (or DO_NOT_TRACK=true) in your environment instead.

---

🗺️ Roadmap

Phase 10: Complete Day-0 to Day-N Lifecycle Mastery (Current)

Goal: Zero-Console Production Independence. Eliminate the final architectural, data, and operational triggers that force developers to open the AWS Management Console across the entire application lifecycle.

👉 See what's shipped and what's next in the full roadmap

---

📜 License

Distributed under the MIT License. See LICENSE for more information.