deploy-stack 0.14.3 → 0.15.1

package/README.md

@@ -30,7 +30,7 @@ You retain complete ownership of your infrastructure code without relying on bla
 **🚀 Zero-Config Deployments**
 * **Framework Agnostic:** Tailored container presets for Next.js, Express.js, FastAPI, Go, Django, Rails, Nuxt 3, and Static Sites (React, Vue, SvelteKit, Astro).
 * **Smart Discovery:** Automatically detects build output directories and generates highly optimized, multi-stage Dockerfiles.
-* **PaaS Migration Engine:** Natively parses Heroku `Procfile` configurations and `vercel.json` files to automatically translate proprietary edge routing (redirects/rewrites) and background workers into standard AWS Fargate and Application Load Balancer architectures.
+* **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 RDS PostgreSQL databases for backend monoliths.
 
 **🛡️ DevSecOps & Security**
@@ -124,18 +124,11 @@ 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.
-* **[Create React App](https://github.com/anton-codes-iac/deploy-stack-cra-example):** Validates backward compatibility with legacy Webpack pipelines and `build/` auto-detection.
-* **[Astro Static Site](https://github.com/anton-codes-iac/deploy-stack-astro-example):** Demonstrates modern static site generation (SSG).
-* **[SvelteKit Application](https://github.com/anton-codes-iac/deploy-stack-svelte-example):** Demonstrates static adapter integration and custom output folder detection.
-* **[Ruby on Rails](https://github.com/anton-codes-iac/deploy-stack-rails-example):** A production Rails 7+ setup featuring an auto-provisioned PostgreSQL database and secure `.auto.tfvars` Master Key injection.
-* **[Nuxt 3 (SSR)](https://github.com/anton-codes-iac/deploy-stack-nuxt-example):** Demonstrates a fully server-side rendered Nuxt application using Nitro's optimized Node output.
-* **[Django / Python](https://github.com/anton-codes-iac/deploy-stack-django-example):** A secure Gunicorn/WSGI implementation with PostgreSQL and unprivileged container adapters.
-* **[Heroku to AWS Migration (Django)](https://github.com/anton-codes-iac/deploy-stack-heroku-django-example):** A classic Heroku-style monolith migrated via the Procfile Importer, demonstrating a multi-container Web and Celery Worker architecture deployed from a single codebase.
-* **[Go / Fiber](https://github.com/anton-codes-iac/deploy-stack-go-example):** A distroless, compiled Go binary deployment demonstrating ultra-low memory footprints and instant boot times.
+* **[Docker Compose to AWS Migration](https://github.com/anton-codes-iac/deploy-stack-docker-compose-example):** 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)](https://github.com/anton-codes-iac/deploy-stack-heroku-django-example):** A classic Heroku-style monolith migrated via the Procfile Importer.
+
+👉 **[View all 14+ reference implementations in our Examples Gallery](./docs/examples.md)**
+
 ---
 
 ## 🛡️ Telemetry & Privacy
@@ -150,28 +143,14 @@ npx deploy-stack --no-telemetry
 
 ## 🗺️ Roadmap
 
-### Phase 1–3: The Core Engine (Completed)
-- [x] **Core MVP:** Interactive CLI, ECS Fargate + ALB generation, CI/CD, and Secrets sync.
-- [x] **Production Readiness:** CloudFront CDN edge distribution, native S3 state locking, and secure OIDC integration.
-- [x] **Smart Experience:** Zero-config framework auto-discovery for static output directories.
-- [x] **Trust & Observability:** DevSecOps Trivy scanning, automated 5XX alarms, 14-day log retention, and safe local overwrite protections.
-
-### Phase 4: Trust Anchors & TAM Expansion (Completed)
-- [x] **Ecosystem Distribution:** Native GitHub Marketplace Action for rapid discovery.
-- [x] **Cost Transparency:** Pre-flight AWS cost estimator injected directly into the CLI wizard.
-- [x] **Zero Vendor Lock-In:** Explicit `npx deploy-stack eject` command to safely strip `ManagedBy` tags and CLI metadata, leaving behind pure IaC.
-- [x] **Heavy Backend Monoliths:** Hardened, unprivileged container adapters for Go, Nuxt.js, Django, and Rails, complete with automated zero-trust RDS PostgreSQL provisioning.
-
-### Phase 5: The Activation Engine (Completed)
-- [x] **Local Execution Wrapper:** Native `deploy-stack apply` command with terminal-optimized streaming to eliminate Terraform context switching.
-- [x] **Ecosystem Integrations:** Official plugins published to the Astro Integrations directory (`astro-deploy-stack`) and Nuxt module registry (`nuxt-deploy-stack`).
-
-### Phase 6: Migration & Trust Engine (Current)
+### Current Focus (Phase 6: Migration & Trust Engine)
 - [x] **Dry-Run Visualization:** Interactive pre-flight terminal UI with ASCII topology maps and precise, dynamic AWS cost estimation.
 - [x] **PaaS Importers:** Auto-parse `vercel.json` and Heroku `Procfile` configurations to map routing rules, web commands, and background workers automatically.
-- [ ] **Docker Compose to ECS Translator:** Automatically converting a familiar local `docker-compose.yml` into production ECS task definitions.
+- [x] **Docker Compose to ECS Translator:** Automatically converting a familiar local `docker-compose.yml` into production ECS task definitions.
 - [ ] **AI Agent Rulesets:** Publishing `.cursorrules` and Copilot instructions that teach AI assistants exactly how to utilize the CLI on the user's behalf.
 
+👉 **[See the full project history and future plans in ROADMAP.md](./ROADMAP.md)**
+
 ---
 
 ## 📜 License

package/docs/ROADMAP.md

@@ -0,0 +1,23 @@
+# 🗺️ deploy-stack Roadmap
+
+### Phase 1–3: The Core Engine (Completed)
+- [x] **Core MVP:** Interactive CLI, ECS Fargate + ALB generation, CI/CD, and Secrets sync.
+- [x] **Production Readiness:** CloudFront CDN edge distribution, native S3 state locking, and secure OIDC integration.
+- [x] **Smart Experience:** Zero-config framework auto-discovery for static output directories.
+- [x] **Trust & Observability:** DevSecOps Trivy scanning, automated 5XX alarms, 14-day log retention, and safe local overwrite protections.
+
+### Phase 4: Trust Anchors & TAM Expansion (Completed)
+- [x] **Ecosystem Distribution:** Native GitHub Marketplace Action for rapid discovery.
+- [x] **Cost Transparency:** Pre-flight AWS cost estimator injected directly into the CLI wizard.
+- [x] **Zero Vendor Lock-In:** Explicit `npx deploy-stack eject` command to safely strip `ManagedBy` tags and CLI metadata, leaving behind pure IaC.
+- [x] **Heavy Backend Monoliths:** Hardened, unprivileged container adapters for Go, Nuxt.js, Django, and Rails, complete with automated zero-trust RDS PostgreSQL provisioning.
+
+### Phase 5: The Activation Engine (Completed)
+- [x] **Local Execution Wrapper:** Native `deploy-stack apply` command with terminal-optimized streaming to eliminate Terraform context switching.
+- [x] **Ecosystem Integrations:** Official plugins published to the Astro Integrations directory (`astro-deploy-stack`) and Nuxt module registry (`nuxt-deploy-stack`).
+
+### Phase 6: Migration & Trust Engine (Current)
+- [x] **Dry-Run Visualization:** Interactive pre-flight terminal UI with ASCII topology maps and precise, dynamic AWS cost estimation.
+- [x] **PaaS Importers:** Auto-parse `vercel.json` and Heroku `Procfile` configurations to map routing rules, web commands, and background workers automatically.
+- [x] **Docker Compose to ECS Translator:** Automatically converting a familiar local `docker-compose.yml` into production ECS task definitions.
+- [ ] **AI Agent Rulesets:** Publishing `.cursorrules` and Copilot instructions that teach AI assistants exactly how to utilize the CLI on the user's behalf.

package/docs/examples.md

@@ -0,0 +1,23 @@
+# 📦 Reference Implementations & Examples
+
+These repositories demonstrate how `deploy-stack` handles various frameworks and architectural patterns. Each example includes the auto-generated Terraform, GitHub Actions, and container configurations.
+
+### Featured Migrations
+* **[Heroku to AWS Migration (Django)](https://github.com/anton-codes-iac/deploy-stack-heroku-django-example):** A classic Heroku-style monolith migrated via the Procfile Importer, demonstrating a multi-container Web and Celery Worker architecture deployed from a single codebase.
+* **[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.
+* **[Docker Compose to AWS Migration](https://github.com/anton-codes-iac/deploy-stack-docker-compose-example):** Demonstrates automatic translation of local `docker-compose.yml` sidecars (like Redis) into a multi-container AWS ECS Task Definition communicating over `localhost`.
+
+### Frontend & Fullstack Frameworks
+* **[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.
+* **[Vite / React SPA](https://github.com/anton-codes-iac/deploy-stack-vite-example):** Demonstrates SPA routing and `dist/` auto-detection.
+* **[Create React App](https://github.com/anton-codes-iac/deploy-stack-cra-example):** Validates backward compatibility with legacy Webpack pipelines and `build/` auto-detection.
+* **[Astro Static Site](https://github.com/anton-codes-iac/deploy-stack-astro-example):** Demonstrates modern static site generation (SSG).
+* **[SvelteKit Application](https://github.com/anton-codes-iac/deploy-stack-svelte-example):** Demonstrates static adapter integration and custom output folder detection.
+* **[Nuxt 3 (SSR)](https://github.com/anton-codes-iac/deploy-stack-nuxt-example):** Demonstrates a fully server-side rendered Nuxt application using Nitro's optimized Node output.
+
+### Backend APIs & Monoliths
+* **[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.
+* **[Ruby on Rails](https://github.com/anton-codes-iac/deploy-stack-rails-example):** A production Rails 7+ setup featuring an auto-provisioned PostgreSQL database and secure `.auto.tfvars` Master Key injection.
+* **[Django / Python](https://github.com/anton-codes-iac/deploy-stack-django-example):** A secure Gunicorn/WSGI implementation with PostgreSQL and unprivileged container adapters.
+* **[Go / Fiber](https://github.com/anton-codes-iac/deploy-stack-go-example):** A distroless, compiled Go binary deployment demonstrating ultra-low memory footprints and instant boot times.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deploy-stack",
-  "version": "0.14.3",
+  "version": "0.15.1",
   "description": "Provision production-ready AWS infrastructure and CI/CD pipelines in seconds.",
   "engines": {
     "node": ">=18.0.0"
@@ -46,6 +46,7 @@
     "@aws-sdk/client-sts": "3.1115.0",
     "@clack/prompts": "1.7.0",
     "dotenv": "17.4.2",
+    "js-yaml": "5.4.1",
     "picocolors": "1.1.1"
   }
 }

package/src/commands/init.js

@@ -20,6 +20,7 @@ import { handleExistingFiles } from '../utils/backup.js';
 import { estimateMonthlyCost } from '../utils/visualizer.js';
 import { getTargetDirectory, getProjectConfig } from '../utils/prompts.js';
 import { resolveDjangoWsgi, handleRailsCI } from '../utils/frameworks.js';
+import { hasDockerCompose, parseDockerCompose } from '../utils/dockerCompose.js';
 
 const pkg = JSON.parse(fsSync.readFileSync(new URL('../../package.json', import.meta.url)));
 const CLI_VERSION = pkg.version;
@@ -42,11 +43,13 @@ export async function mainStack({ isHeadless = false, headlessOptions = {} } = {
     const detectedFramework = detectFramework(dirConfig.targetDir);
     const procfile = parseProcfile(dirConfig.targetDir);
     const vercelRules = parseVercelConfig(dirConfig.targetDir);
+    const dockerCompose = parseDockerCompose(dirConfig.targetDir);
 
     if (!isHeadless) {
         if (detectedFramework) log.success(`Auto-detected framework: ${detectedFramework.name}`);
         if (procfile && procfile.web) log.success(`Auto-detected Procfile (web command: ${procfile.web.join(' ')})`);
         if (vercelRules) log.success(`Auto-detected vercel.json (Migrating edge network rules)`);
+        if (dockerCompose) log.success(`Auto-detected docker-compose.yml (${dockerCompose.length} services mapped)`);
     }
 
     if (isHeadless) console.log(color.cyan(`🤖 Running deploy-stack in headless mode`));
@@ -56,6 +59,19 @@ export async function mainStack({ isHeadless = false, headlessOptions = {} } = {
     const djangoWsgi = await resolveDjangoWsgi(dirConfig.targetDir, procfile, config.framework, isHeadless);
     const disableDefaultCI = await handleRailsCI(dirConfig.targetDir, config.framework, isHeadless);
 
+    // 3.5 Docker Compose Overrides
+    if (dockerCompose && dockerCompose.length > 0) {
+        // Find the first service that has an exposed port
+        const webService = dockerCompose.find(s => s.port);
+        if (webService && webService.port) {
+            // Override the config port with the one from Docker Compose
+            config.port = webService.port.toString();
+            if (!isHeadless) {
+                console.log(color.cyan(`   🐳 Docker Compose overrides: Port set to ${config.port} via service "${webService.name}"`));
+            }
+        }
+    }
+
     // 4. Framework Migration Checks (Vercel Escape Hatch)
     if (config.framework === 'nextjs') {
         const nextConfig = analyzeNextConfig(dirConfig.targetDir);
@@ -126,7 +142,8 @@ export async function mainStack({ isHeadless = false, headlessOptions = {} } = {
         DJANGO_WSGI: djangoWsgi,
         DISABLE_DEFAULT_CI: disableDefaultCI,
         PROCFILE: procfile,
-        VERCEL_RULES: vercelRules
+        VERCEL_RULES: vercelRules,
+        DOCKER_COMPOSE: dockerCompose
     });
 
     // 8. Telemetry
@@ -151,6 +168,7 @@ export async function mainStack({ isHeadless = false, headlessOptions = {} } = {
         has_worker: !!(procfile && procfile.worker),
         is_heroku_migration: !!procfile,
         is_vercel_migration: !!vercelRules,
+        is_docker_compose: !!dockerCompose,
     });
 
     s.stop('Infrastructure provisioned successfully!');

package/src/utils/dockerCompose.js

@@ -0,0 +1,64 @@
+import fs from 'fs';
+import path from 'path';
+import { load } from 'js-yaml';
+
+// 1. Check if a Docker Compose file exists in the target directory.
+export function hasDockerCompose(targetDir) {
+    return fs.existsSync(path.join(targetDir, 'docker-compose.yml')) ||
+        fs.existsSync(path.join(targetDir, 'docker-compose.yaml'));
+}
+
+// 2. Parse docker-compose.yml and normalize it into an array of services.
+export function parseDockerCompose(targetDir) {
+    let composePath = path.join(targetDir, 'docker-compose.yml');
+    if (!fs.existsSync(composePath)) {
+        composePath = path.join(targetDir, 'docker-compose.yaml');
+    }
+
+    if (!fs.existsSync(composePath)) return null;
+
+    try {
+        const fileContents = fs.readFileSync(composePath, 'utf8');
+        const data = load(fileContents);
+
+        if (!data || !data.services) return null;
+
+        const services = [];
+
+        for (const [name, config] of Object.entries(data.services)) {
+            // Extract the container port (e.g., "8080:80" -> 80)
+            let exposedPort = null;
+            if (config.ports && config.ports.length > 0) {
+                // Handle different port formats like "3000" or "8000:8000" or "127.0.0.1:8001:8001"
+                const portMapping = config.ports[0].toString();
+                const parts = portMapping.split(':');
+                exposedPort = parseInt(parts[parts.length - 1].replace(/[^0-9]/g, ''), 10);
+            }
+
+            // Normalize environment variables from Array or Object
+            let envVars = {};
+            if (Array.isArray(config.environment)) {
+                config.environment.forEach(env => {
+                    const [key, ...val] = env.split('=');
+                    if (key) envVars[key] = val.join('=');
+                });
+            } else if (typeof config.environment === 'object') {
+                envVars = config.environment;
+            }
+
+            services.push({
+                name,
+                build: config.build || null,
+                image: config.image || null,
+                port: exposedPort,
+                command: config.command || null,
+                environment: envVars
+            });
+        }
+
+        return services;
+    } catch (e) {
+        console.error('⚠️ Failed to parse Docker Compose file:', e.message);
+        return null;
+    }
+}

package/src/utils/generator.js

@@ -62,6 +62,60 @@ export async function generateTemplates(targetDir, config) {
         config.DB_ENV_VARS = '';
     }
 
+    // 3.3. Docker Compose Overrides & Sidecars
+    let composeWebEnvVars = [];
+    let extraContainersHCL = "";
+
+    if (config.DOCKER_COMPOSE && config.DOCKER_COMPOSE.length > 0) {
+        // Identify the main web service (the one with the exposed port)
+        const webService = config.DOCKER_COMPOSE.find(s => s.port) || config.DOCKER_COMPOSE[0];
+
+        // Extract Web Env Vars
+        if (webService.environment) {
+            for (const [key, val] of Object.entries(webService.environment)) {
+                composeWebEnvVars.push(`{ "name": "${key}", "value": "${val}" }`);
+            }
+        }
+
+        // Extract Web Command Override (only if Procfile hasn't already set it)
+        if (webService.command && !config.TASK_COMMAND) {
+            config.TASK_COMMAND = `command = ${JSON.stringify(typeof webService.command === 'string' ? webService.command.split(' ') : webService.command)}`;
+        }
+
+        // Process Sidecar Containers (e.g., Redis, Memcached)
+        const sidecars = config.DOCKER_COMPOSE.filter(s => s.name !== webService.name);
+        if (sidecars.length > 0) {
+            extraContainersHCL = sidecars.map(service => {
+                const sidecarEnv = Object.entries(service.environment || {})
+                    .map(([k, v]) => `{ "name": "${k}", "value": "${String(v).replace(/"/g, '\\"')}" }`)
+                    .join(',\n        ');
+
+                const sidecarCmd = service.command ? `\n      command = ${JSON.stringify(typeof service.command === 'string' ? service.command.split(' ') : service.command)}` : '';
+
+                return `,
+    {
+      name      = "${service.name}"
+      image     = "${service.image || 'alpine:latest'}"
+      essential = true
+      environment = [
+        ${sidecarEnv}
+      ]${sidecarCmd}
+      logConfiguration = {
+        logDriver = "awslogs"
+        options = {
+          "awslogs-group"         = aws_cloudwatch_log_group.app_logs.name
+          "awslogs-region"        = "${config.REGION}"
+          "awslogs-stream-prefix" = "ecs-${service.name}"
+        }
+      }
+    }`;
+            }).join('');
+        }
+    }
+
+    config.COMPOSE_WEB_ENV_VARS = composeWebEnvVars.length > 0 ? composeWebEnvVars.join(',\n        ') + ',' : '';
+    config.EXTRA_CONTAINERS = extraContainersHCL;
+
     // 4. Configure AWS Secrets Manager Integration
     // Build the initial HCL map for AWS Secrets Manager
     let initialSecretMap = `{\n    EXAMPLE_API_KEY = "replace_me_in_aws_console"`;

package/templates/docker/node.Dockerfile

@@ -1,18 +1,22 @@
 FROM node:22-alpine
 
-# 1. Set production environment (optimizes Node and prevents dev dependencies)
+# 1. DevSecOps: Patch underlying Alpine OS vulnerabilities and update global npm
+RUN apk update && apk upgrade --no-cache && \
+    npm install -g npm@latest
+
+# 2. Set production environment (optimizes Node and prevents dev dependencies)
 ENV NODE_ENV=production
 
 WORKDIR /app
 
-# 2. Copy dependency manifests with non-root ownership
+# 3. Copy dependency manifests with non-root ownership
 COPY --chown=node:node package*.json ./
 RUN npm ci --omit=dev
 
-# 3. Copy application code with non-root ownership
+# 4. Copy application code with non-root ownership
 COPY --chown=node:node . .
 
-# 4. DevSecOps best practice: do not run the container as root
+# 5. DevSecOps best practice: do not run the container as root
 USER node
 
 EXPOSE {{PORT}}

package/templates/terraform/main.tf

@@ -83,6 +83,7 @@ resource "aws_ecs_task_definition" "app" {
       essential = true
 
       environment = [
+        {{COMPOSE_WEB_ENV_VARS}}
         {{DB_ENV_VARS}}
       ]
 
@@ -117,7 +118,7 @@ resource "aws_ecs_task_definition" "app" {
           "awslogs-stream-prefix" = "ecs"
         }
       }
-    }
+    }{{EXTRA_CONTAINERS}}
   ])
 }