deploy-stack 0.14.0 → 0.14.2

package/README.md

@@ -51,6 +51,15 @@ You retain complete ownership of your infrastructure code without relying on bla
 
 ---
 
+## 📚 Documentation & Guides
+Transitioning from PaaS to AWS involves a few architectural shifts. We've written concise guides to help you understand how `deploy-stack` handles the heavy lifting:
+* [Migrating from Heroku to AWS (Procfile Support)](./docs/migrations/heroku-procfile-to-aws.md)
+* [Managing Secrets & Environment Variables](./docs/guides/secrets-management.md)
+* [Zero-Trust Database Connections](./docs/guides/database-connections.md)
+* [Migrating Next.js from Vercel](./docs/migrations/nextjs-vercel-to-aws.md)
+
+---
+
 ## 🚀 Quick Start
 
 Run the CLI directly in your project root:
@@ -115,6 +124,7 @@ your-project/
 ## 📦 Reference Implementations
 
 * **[Next.js Fullstack App](https://github.com/anton-codes-iac/deploy-stack-nextjs-example):** A complete Next.js deployment showcasing the generated Terraform, CloudFront setup, and automated OIDC workflow.
+* **[Vercel to AWS Migration (Next.js)](https://github.com/anton-codes-iac/deploy-stack-vercel-nextjs-example):** Demonstrates automatic translation of Vercel edge routing (`vercel.json`) to native AWS Application Load Balancer rules.
 * **[Express.js API](https://github.com/anton-codes-iac/deploy-stack-express-example):** A standard Node.js backend setup.
 * **[Python FastAPI](https://github.com/anton-codes-iac/deploy-stack-fastapi-example):** A Python API demonstrating unprivileged port mapping.
 * **[Vite / React SPA](https://github.com/anton-codes-iac/deploy-stack-vite-example):** Demonstrates SPA routing and `dist/` auto-detection.

package/docs/guides/database-connections.md

@@ -0,0 +1,27 @@
+# Managed Database Connections
+
+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.
+
+## Zero-Trust Architecture
+
+If you select "Yes", `deploy-stack` builds a true zero-trust network topology:
+1. The PostgreSQL instance is deployed into heavily restricted **Isolated Subnets**.
+2. It is given a strict Security Group that *only* allows inbound traffic from your specific ECS Fargate containers on port `5432`.
+3. The database is completely inaccessible from the public internet.
+
+## Auto-Injected Environment Variables
+
+You do not need to configure database connection strings manually. The generated Terraform automatically creates a secure, random master password in AWS Secrets Manager and injects the following environment variables directly into your running containers:
+
+* `DB_HOST` (The internal AWS DNS endpoint)
+* `DB_PORT` (5432)
+* `DB_NAME` (Your auto-generated database name)
+* `DB_USER` (Injected securely at runtime)
+* `DB_PASSWORD` (Injected securely at runtime)
+
+To connect your application, simply configure your ORM (Prisma, Django, TypeORM, Active Record) to read from these standard environment variables.
+
+## Running Database Migrations
+
+Because the database is in an isolated subnet, you cannot run schema migrations directly from your local laptop. 
+The best practice is to configure your CI/CD pipeline or your Docker container's startup script to run your migrations (e.g., `npx prisma deploy` or `python manage.py migrate`) before starting the main web process.

package/docs/guides/secrets-management.md

@@ -0,0 +1,24 @@
+# Secrets Management in deploy-stack
+
+Managing `.env` files across a team and syncing them to the cloud is a notorious pain point. `deploy-stack` solves this by natively integrating with **AWS Secrets Manager**, ensuring zero plaintext secrets ever touch your GitHub repository or CI/CD pipelines.
+
+## Pushing Secrets to AWS
+
+Instead of manually clicking through the AWS Console, use the built-in secrets command:
+
+```bash
+npx deploy-stack secrets push .env.production
+```
+
+### What happens under the hood?
+1. The CLI reads your local `.env.production` file.
+2. It encrypts the key-value pairs and pushes them securely into AWS Secrets Manager under your project's namespace (e.g., `my-project-secrets`).
+3. It generates a local `terraform/secret_keys.json` file containing *only the names* of your keys (e.g., `["API_KEY", "STRIPE_SECRET"]`), **not the values**.
+
+## How Secrets Reach Your App
+
+When you commit `terraform/secret_keys.json` and push to GitHub, your CI/CD pipeline runs Terraform. 
+
+Terraform reads the JSON array of key names and dynamically maps them to your ECS Task Definition. When your AWS Fargate container boots up, it automatically injects those secrets directly into your application's environment as standard environment variables (e.g., `process.env.STRIPE_SECRET` or `os.getenv("API_KEY")`).
+
+*Note: Because Terraform maps the secrets at runtime, updating a secret value in AWS and running an empty GitHub deployment will instantly cycle your containers with the new keys!*

package/docs/migration/astro-vercel-to-aws.md

@@ -0,0 +1,47 @@
+# Migrating Astro from Vercel to AWS Fargate
+
+If you are seeing a warning from `deploy-stack` about your Astro adapter, it means your project is currently configured to build specifically for Vercel's proprietary serverless network. 
+
+To deploy Astro as a containerized application on standard AWS infrastructure, you simply need to switch to Astro's official Node.js adapter.
+
+## How to Fix
+
+### 1. Install the Node adapter
+Run the following command in your terminal to swap out the Vercel adapter for the Node adapter:
+
+\`\`\`bash
+npm install @astrojs/node
+npm uninstall @astrojs/vercel
+\`\`\`
+
+### 2. Update `astro.config.mjs`
+Open your Astro configuration file and replace the Vercel import with the Node import.
+
+**Before (Vercel Lock-in):**
+\`\`\`javascript
+import { defineConfig } from 'astro/config';
+import vercel from '@astrojs/vercel/serverless';
+
+export default defineConfig({
+  output: 'server',
+  adapter: vercel(),
+});
+\`\`\`
+
+**After (AWS Ready):**
+\`\`\`javascript
+import { defineConfig } from 'astro/config';
+import node from '@astrojs/node';
+
+export default defineConfig({
+  output: 'server',
+  adapter: node({
+    mode: 'standalone'
+  }),
+});
+\`\`\`
+
+### 3. Deploy
+That's it! Your Astro app is now decoupled from Vercel. 
+
+Run `npx deploy-stack apply` and the CLI will automatically package this standalone Node server into a hardened Docker container and deploy it to your AWS cluster.

package/docs/migration/heroku-procfile-to-aws.md

@@ -0,0 +1,32 @@
+# Migrating from Heroku to AWS (Procfile Support)
+
+When migrating from Heroku or Render, you likely rely on a `Procfile` to define your application's architecture (e.g., a web server and a background worker like Celery or Sidekiq). 
+
+`deploy-stack` natively understands Heroku `Procfile` syntax and automatically translates it into a production-grade, multi-container AWS architecture.
+
+## How it Works
+
+When you run `npx deploy-stack`, the CLI scans your root directory for a `Procfile`. 
+
+### The `web` Process
+If the CLI detects a `web:` declaration:
+1. It overrides the default Docker `CMD`.
+2. It provisions an AWS ECS Fargate service for this process.
+3. It automatically wires this specific container to your public-facing Application Load Balancer (ALB) so it can receive internet traffic.
+
+### The `worker` Process
+If the CLI detects a `worker:` declaration:
+1. It generates a completely separate ECS Fargate task definition (`worker.tf`).
+2. It spins up the worker in a **fully isolated private subnet**.
+3. It intentionally strips all public ingress, ensuring your background workers are secure and can only communicate with your database or message brokers internally.
+
+## Example
+
+**Your `Procfile`:**
+```text
+web: gunicorn myapp.wsgi
+worker: celery -A myapp worker -l info
+```
+
+**The Result:**
+Running `deploy-stack` will automatically generate the Terraform required to spin up both containers simultaneously from the exact same Docker image, scaling them independently based on your needs.

package/docs/migration/nextjs-vercel-to-aws.md

@@ -0,0 +1,43 @@
+# Migrating Next.js from Vercel to AWS Fargate
+
+If you are seeing a warning from `deploy-stack` about `output: 'standalone'`, your Next.js configuration is missing a crucial setting required for containerized environments.
+
+By default, Next.js requires your entire `node_modules` folder to run the production server. This creates massive, bloated Docker containers that boot slowly and cost more to host. The `standalone` output mode tells Next.js to trace your code and bundle *only* the specific files and dependencies actually used in production, creating an ultra-lean deployment artifact.
+
+## How to Fix
+
+### 1. Update `next.config.js` (or `.mjs` / `.cjs`)
+Open your Next.js configuration file in the root of your project and add `output: 'standalone'` to the configuration object.
+
+**Before (Vercel Default):**
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  // Other existing config...
+};
+
+export default nextConfig;
+```
+
+**After (AWS Ready):**
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  output: 'standalone', // <-- Add this line
+  // Other existing config...
+};
+
+export default nextConfig;
+```
+
+### 2. (Optional) Define a Health Check Route
+AWS Application Load Balancers require a route to ping to ensure your app is healthy. If you don't already have one, create a simple API route in your app (e.g., `app/api/health/route.ts` for App Router, or `pages/api/health.ts` for Pages Router) that returns a `200 OK` status.
+
+When running `deploy-stack`, choose **Advanced Configuration** and set your ALB Health Check Path to this route (e.g., `/api/health`).
+
+### 3. Deploy
+Your Next.js app is now perfectly optimized for AWS ECS Fargate! 
+
+Run `npx deploy-stack apply`. The CLI's generated `Dockerfile` will automatically target your new `.next/standalone` directory and deploy the optimized build to the cloud.

package/docs/migration/sveltekit-vercel-to-aws.md

@@ -0,0 +1,55 @@
+# Migrating SvelteKit from Vercel to AWS Fargate
+
+If you are seeing a warning from `deploy-stack` about your SvelteKit adapter, your project is currently using `@sveltejs/adapter-auto` (which often defaults to Vercel) or the explicit `@sveltejs/adapter-vercel`.
+
+These adapters are designed specifically for proprietary serverless edge networks. To run your SvelteKit app in a scalable, standard Docker container on AWS Fargate, you need to switch to Svelte's official Node adapter.
+
+## How to Fix
+
+### 1. Install the Node Adapter
+Run the following command in your terminal to install the Node adapter and remove the Vercel/Auto adapter:
+
+```bash
+npm install -D @sveltejs/adapter-node
+npm uninstall @sveltejs/adapter-auto @sveltejs/adapter-vercel
+```
+
+### 2. Update `svelte.config.js`
+Open your `svelte.config.js` file and change the adapter import at the top of the file.
+
+**Before (Locked into Vercel/Auto):**
+```javascript
+import adapter from '@sveltejs/adapter-auto'; // or '@sveltejs/adapter-vercel'
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+	preprocess: vitePreprocess(),
+	kit: {
+		adapter: adapter()
+	}
+};
+
+export default config;
+```
+
+**After (AWS Ready):**
+```javascript
+import adapter from '@sveltejs/adapter-node';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+	preprocess: vitePreprocess(),
+	kit: {
+		adapter: adapter()
+	}
+};
+
+export default config;
+```
+
+### 3. Deploy
+Your SvelteKit app is now decoupled! 
+
+Run `npx deploy-stack apply`. The CLI will automatically detect the standard Node build output, package it into a hardened Docker container, and deploy it to your AWS cluster.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deploy-stack",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "description": "Provision production-ready AWS infrastructure and CI/CD pipelines in seconds.",
   "engines": {
     "node": ">=18.0.0"

package/release_notes.md

@@ -0,0 +1,7 @@
+# 📝 Architecture Overview & Vercel Example
+
+This patch release improves the documentation generated for end-users and adds the Vercel migration reference implementation to our ecosystem.
+
+### 📖 What's New
+* **Template Architecture Overview:** The auto-generated `README.md` placed in user repositories now includes a high-level "Architecture Overview". This ensures developers understand the AWS topology (ECS Fargate, ALB, IAM OIDC, S3 State) they just provisioned before diving into deployment commands.
+* **Vercel Example Linked:** Officially linked the `deploy-stack-vercel-nextjs-example` repository in the main project README, providing users a direct reference for migrating edge routing (`vercel.json`) and Next.js standalone configurations to AWS.

package/src/commands/init.js

@@ -57,22 +57,23 @@ export async function mainStack({ isHeadless = false, headlessOptions = {} } = {
     const disableDefaultCI = await handleRailsCI(dirConfig.targetDir, config.framework, isHeadless);
 
     // 4. Framework Migration Checks (Vercel Escape Hatch)
-    if (!isHeadless) {
-        if (config.framework === 'nextjs') {
-            const nextConfig = analyzeNextConfig(dirConfig.targetDir);
-            if (nextConfig.hasConfig && !nextConfig.isStandalone) {
-                log.warn(color.yellow('⚠️ Next.js config is missing "output: \'standalone\'". Your CI/CD Docker build will crash until you add it!'));
-            }
-        } else if (detectedFramework?.name === 'SvelteKit') {
-            const svelteConfig = analyzeSvelteConfig(dirConfig.targetDir);
-            if (svelteConfig.adapter === 'vercel' || svelteConfig.adapter === 'auto') {
-                log.warn(color.yellow('⚠️ SvelteKit is locked into the Vercel/Auto adapter. Switch to @sveltejs/adapter-node (for SSR) to deploy on AWS.'));
-            }
-        } else if (detectedFramework?.name === 'Astro') {
-            const astroConfig = analyzeAstroConfig(dirConfig.targetDir);
-            if (astroConfig.adapter === 'vercel') {
-                log.warn(color.yellow('⚠️ Astro is locked into the Vercel adapter. Switch to @astrojs/node (for SSR) to deploy on AWS.'));
-            }
+    if (config.framework === 'nextjs') {
+        const nextConfig = analyzeNextConfig(dirConfig.targetDir);
+        if (nextConfig.hasConfig && !nextConfig.isStandalone) {
+            log.warn(color.yellow('⚠️ Next.js config is missing "output: \'standalone\'".'));
+            console.log(color.cyan('   Fix it here: https://github.com/anton-codes-iac/deploy-stack/blob/main/docs/migrations/nextjs-vercel-to-aws.md'));
+        }
+    } else if (detectedFramework?.name === 'SvelteKit') {
+        const svelteConfig = analyzeSvelteConfig(dirConfig.targetDir);
+        if (svelteConfig.adapter === 'vercel' || svelteConfig.adapter === 'auto') {
+            log.warn(color.yellow('⚠️ SvelteKit is locked into the Vercel/Auto adapter.'));
+            console.log(color.cyan('   Fix it here: https://github.com/anton-codes-iac/deploy-stack/blob/main/docs/migrations/sveltekit-vercel-to-aws.md'));
+        }
+    } else if (detectedFramework?.name === 'Astro') {
+        const astroConfig = analyzeAstroConfig(dirConfig.targetDir);
+        if (astroConfig.adapter === 'vercel') {
+            log.warn(color.yellow('⚠️ Astro is locked into the Vercel adapter.'));
+            console.log(color.cyan('   Fix it here: https://github.com/anton-codes-iac/deploy-stack/blob/main/docs/migrations/astro-vercel-to-aws.md'));
         }
     }
 
@@ -167,6 +168,13 @@ export async function mainStack({ isHeadless = false, headlessOptions = {} } = {
         ? `git add . && git commit -m "chore: add AWS infrastructure and CI/CD" && git push`
         : `git init && git add . && git commit -m "chore: add AWS infrastructure and CI/CD" && git branch -M ${config.branch} && git remote add origin https://github.com/your-username/your-repo.git && git push -u origin ${config.branch}`;
 
+    let docsTip = '';
+    if (procfile) {
+        docsTip = `\n  ${color.blue('📘 Read the Heroku Migration Guide:')} ${color.underline('https://github.com/anton-codes-iac/deploy-stack/blob/main/docs/migrations/heroku-procfile-to-aws.md')}`;
+    } else if (config.needsDatabase) {
+        docsTip = `\n  ${color.blue('📘 Read the Database Connections Guide:')} ${color.underline('https://github.com/anton-codes-iac/deploy-stack/blob/main/docs/guides/database-connections.md')}`;
+    }
+
     outro(`${color.green('✅ Templates generated!')} ${color.blue('🛡️ DevSecOps scanning enabled.')}
     ${frameworkWarnings ? `\n  ${frameworkWarnings}` : ''}
     ${color.yellow('Next steps:')}

package/src/commands/secrets.js

@@ -42,6 +42,7 @@ export async function pushSecrets(envFilePath, projectName) {
         s.stop(`✅ Successfully pushed ${Object.keys(parsedSecrets).length} secrets to AWS!`);
         console.log(color.cyan(`\nUpdated ${keysFilePath}`));
         console.log(color.green('Commit this file and push to GitHub to trigger a deployment with your new variables.'));
+        console.log(color.blue(`\n📘 Learn how secrets reach your app: ${color.underline('https://github.com/anton-codes-iac/deploy-stack/blob/main/docs/guides/secrets-management.md')}`));
 
         trackEvent('secrets_pushed', {
             projectName,

package/templates/README.md

@@ -4,6 +4,14 @@
 > 
 > It contains a production-ready AWS ECS Fargate architecture and a zero-secret GitHub Actions deployment pipeline.
 
+## 🏗️ Architecture Overview
+
+Your application has been configured for an enterprise-grade AWS deployment. Instead of relying on a black-box PaaS, you now own the underlying infrastructure:
+* **Compute:** Your app is packaged into a Docker container and runs on **AWS ECS Fargate** (Serverless compute, meaning no EC2 instances to manage).
+* **Networking:** Traffic flows through an **Application Load Balancer (ALB)**, which sits inside a custom VPC across multiple Availability Zones for high availability.
+* **Security:** Deployments are handled via GitHub Actions using **AWS IAM OIDC**. This means GitHub securely requests temporary tokens to deploy your code—no long-lived AWS keys are stored anywhere.
+* **State Management:** Terraform state is securely backed by an encrypted S3 bucket with DynamoDB locking.
+
 ## 💰 Cost Estimate & Disclaimer
 
 This infrastructure provisions a highly available Application Load Balancer (ALB) and an ECS Fargate container (Size: **{{COMPUTE_TIER}}**).
@@ -16,11 +24,11 @@ This infrastructure provisions a highly available Application Load Balancer (ALB
 ## 🚀 Deployment Guide
 
 1. **Initial Provisioning:**
+   Ensure you have configured your AWS CLI locally, then run the native deploy command:
    ```bash
-   cd terraform
-   terraform init
-   terraform apply
+   npx deploy-stack apply
    ```
+   *(Alternatively, run `cd terraform && terraform init && terraform apply`)*
 
 2. **Push Secrets (Optional):**
    If your application requires environment variables, create a local `.env` file and sync it directly to AWS Secrets Manager:
@@ -28,8 +36,8 @@ This infrastructure provisions a highly available Application Load Balancer (ALB
    npx deploy-stack secrets push .env
    ```
 
-3. **Automated CI/CD (Keyless via OIDC):**
-   Push this repository to GitHub. Your deployment pipeline uses the official [deploy-stack GitHub Action](https://github.com/marketplace/actions/deploy-stack-aws-fargate-terraform-deploy) and AWS IAM OpenID Connect (OIDC) to authenticate securely with temporary credentials—**no long-lived AWS secret keys are required in GitHub Secrets**. Every push to `{{DEPLOY_BRANCH}}` will automatically run your infrastructure changes, build your container, and deploy your application.
+3. **Automated CI/CD:**
+   Push this repository to GitHub. Your deployment pipeline uses the official [deploy-stack GitHub Action](https://github.com/marketplace/actions/deploy-stack-aws-fargate-terraform-deploy). Every push to `{{DEPLOY_BRANCH}}` will automatically run your infrastructure changes, build your container, and deploy your application.
 
 ### ⚠️ Troubleshooting: OIDC Provider Already Exists
 AWS only permits one GitHub Actions OIDC provider per AWS account. If `terraform apply` fails with an `EntityAlreadyExists` error regarding the OIDC provider, it indicates GitHub Actions was previously configured in this account.
@@ -42,7 +50,7 @@ variable "create_oidc_provider" {
   default = false # <--- Change this from true to false
 }
 ```
-Re-run `terraform apply` to link directly to your existing provider.
+Re-run `npx deploy-stack apply` to link directly to your existing provider.
 
 ## 🛑 Safe Teardown (Destroying the Stack)
 

package/release-notes.md

@@ -1,14 +0,0 @@
-# 🚀 Vercel Escape Hatch, Orchestrator Refactor & Advanced Telemetry
-
-This release introduces the second half of our PaaS Migration Engine, focusing on seamlessly escaping Vercel's proprietary edge network, alongside an internal architectural cleanup.
-
-### ✨ What's New
-* **Vercel Edge Routing Migration:** `deploy-stack` now automatically parses `vercel.json` files. It natively translates Vercel edge redirects (301/302) and regex path matching directly into standard AWS Application Load Balancer Listener Rules.
-* **Vendor Lock-In Detection:** The CLI now proactively analyzes framework configuration files (`next.config.mjs`, `svelte.config.js`, `astro.config.mjs`) during the pre-flight checks. It warns users if they are locked into Vercel-specific adapters and provides exact instructions on how to switch to standard Node/Standalone outputs for AWS containerization.
-
-### 🛠️ Architecture & Telemetry
-* **Core Orchestrator Refactor:** Stripped over 250 lines of business logic and UI prompting out of `init.js`, establishing a clean, strictly isolated `src/utils/` toolbox pattern for future PaaS parsers.
-* **Wide Telemetry Payloads:** Upgraded the analytics engine to capture detailed execution context (CLI version, headless status, desired task counts, and specific migration vectors like Heroku/Vercel) to better map the user deployment funnel.
-
-### 🐛 Bug Fixes
-* **Next.js Standalone Enforcement:** Explicit warnings are now surfaced if a Next.js project is missing the critical `output: 'standalone'` directive before attempting to provision cloud resources.