deploy-stack 0.1.0

package/src/utils/system.js

@@ -0,0 +1,13 @@
+import util from 'util';
+import { exec } from 'child_process';
+
+const execAsync = util.promisify(exec);
+
+export async function checkDependency(command) {
+    try {
+        await execAsync(`${command} --version`);
+        return true;
+    } catch (error) {
+        return false;
+    }
+}

package/templates/README.md

@@ -0,0 +1,85 @@
+# {{PROJECT_NAME}} - Cloud Infrastructure
+
+This project was provisioned by `deploy-stack`. It contains a production-ready AWS ECS Fargate architecture and a GitHub Actions deployment pipeline.
+
+## 💰 Cost Estimate & Disclaimer
+
+This infrastructure provisions a highly available Application Load Balancer (ALB) and an ECS Fargate container (Size: **{{COMPUTE_TIER}}**).
+    
+* **Estimated Monthly Cost:** {{ESTIMATED_COST}}
+* *Note: AWS bills by the hour. If you destroy this stack after a few hours of testing, it will cost less than $0.20.*
+
+> **⚠️ DISCLAIMER:** This cost is a rough estimate. AWS pricing changes and varies by region. **You are solely responsible for all AWS charges incurred by deploying this infrastructure.** The creators of `deploy-stack` are not liable for unexpected cloud costs, compromised credentials, or runaway billing. Always monitor your AWS Billing Dashboard and set up budget alerts.
+
+## 🚀 Deployment Guide
+
+1. **Initial Provisioning:**
+   ```bash
+   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:
+   ```bash
+   npx deploy-stack secrets push .env
+   ```
+
+3. **Automated CI/CD (Keyless via OIDC):**
+   Push this repository to GitHub. Your deployment pipeline uses 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 `main` will automatically build, package, 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.
+
+**The Fix:**
+Open `terraform/oidc.tf` and update the default value of `create_oidc_provider` to `false`:
+```hcl
+variable "create_oidc_provider" {
+  type    = bool
+  default = false # <--- Change this from true to false
+}
+```
+Re-run `terraform apply` to link directly to your existing provider.
+
+## 🛑 Safe Teardown (Destroying the Stack)
+
+If you are done testing and want to stop all AWS billing, you must destroy the infrastructure. 
+
+Because our Terraform configuration is set to force-delete the ECR image repository (even if images are present), teardown is a single, clean command:
+
+```bash
+cd terraform
+terraform destroy
+```
+*Type `yes` when prompted. This will permanently delete the Load Balancer, ECS cluster, log groups, and associated networking components.*
+
+## ⚠️ Critical Application Prerequisites
+
+Before you push your code to GitHub, ensure your application is configured to run inside a Docker container and respond to AWS Load Balancer health checks.
+
+### 1. The Health Check Route (All Frameworks)
+
+AWS constantly pings your container to ensure it is alive. If you configured a custom health check path (e.g., `/api/health`) during the CLI setup, **you must create that route in your application**. If AWS receives a `404 Not Found`, it will assume your app is broken and terminate the container.
+
+Make sure your app returns a `200 OK` at your configured path:
+
+* **Next.js (App Router):** Create `app/api/health/route.ts` returning a 200 response.
+* **Express.js:** Add `app.get('/api/health', (req, res) => res.sendStatus(200));`
+* **FastAPI/Python:** Add `@app.get("/api/health")` returning a 200 status.
+
+### 2. Enable Standalone Output (Next.js ONLY)
+
+Next.js must be configured in "standalone" mode so it can bundle a minimal Node.js server. Without this, your GitHub Actions Docker build will crash.
+    
+Open `next.config.js` or `next.config.ts` in your root directory and add `output: 'standalone'`:
+
+```typescript
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  output: 'standalone', // <--- Add this exact line
+};
+
+export default nextConfig;
+```

package/templates/_gitignore

@@ -0,0 +1,19 @@
+# Terraform
+terraform/.terraform/
+terraform/*.tfstate
+terraform/*.tfstate.backup
+terraform/.terraform.lock.hcl
+terraform/secret_keys.json
+terraform/.terraform.*
+
+# Node & Next.js
+node_modules/
+.next/
+.env
+.env.*
+!.env.example
+
+# Python
+__pycache__/
+*.pyc
+venv/

package/templates/docker/nextjs.Dockerfile

@@ -0,0 +1,32 @@
+# Stage 1: Install dependencies and build the app
+FROM node:20-alpine AS builder
+WORKDIR /app
+
+# Copy package files and install dependencies
+COPY package.json package-lock.json* ./
+RUN npm ci
+
+# Copy the rest of the application code
+COPY . .
+
+# Build the Next.js application
+# (This requires output: 'standalone' in next.config.ts)
+RUN npm run build
+
+# Stage 2: Production environment
+FROM node:20-alpine AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV PORT={{PORT}}
+ENV HOSTNAME="0.0.0.0"
+
+# Copy the standalone output from the builder stage
+COPY --from=builder /app/.next/standalone ./
+COPY --from=builder /app/.next/static ./.next/static
+COPY --from=builder /app/public ./public
+
+EXPOSE {{PORT}}
+
+# Start the standalone Node.js server
+CMD ["node", "server.js"]

package/templates/docker/node.Dockerfile

@@ -0,0 +1,7 @@
+FROM node:18-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm install
+COPY . .
+EXPOSE {{PORT}}
+CMD ["npm", "start"]

package/templates/docker/python.Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+COPY . .
+EXPOSE {{PORT}}
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "{{PORT}}"]

package/templates/docker/static.Dockerfile

@@ -0,0 +1,13 @@
+FROM nginx:alpine
+
+# Remove default Nginx static assets
+RUN rm -rf /usr/share/nginx/html/*
+
+# Copy your static build output (e.g., from Gatsby, React, or pure HTML)
+COPY . /usr/share/nginx/html
+
+# Dynamically update the Nginx config to use the user's chosen port
+RUN sed -i 's/listen  *80;/listen {{PORT}};/g' /etc/nginx/conf.d/default.conf
+
+EXPOSE {{PORT}}
+CMD ["nginx", "-g", "daemon off;"]

package/templates/github/deploy.yml

@@ -0,0 +1,53 @@
+name: Deploy to AWS ECS
+
+on:
+  push:
+    branches:
+      - {{DEPLOY_BRANCH}}
+
+env:
+  AWS_REGION: {{REGION}}
+  ECR_REPOSITORY: {{PROJECT_NAME}}-repo
+  ECS_CLUSTER: {{PROJECT_NAME}}-cluster
+  ECS_SERVICE: {{PROJECT_NAME}}-service
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  deploy:
+    name: Build & Deploy
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::{{AWS_ACCOUNT_ID}}:role/{{PROJECT_NAME}}-github-actions-role
+          aws-region: ${{ env.AWS_REGION }}
+
+      - name: Login to Amazon ECR
+        id: login-ecr
+        uses: aws-actions/amazon-ecr-login@v2
+
+      - name: Build, tag, and push image to Amazon ECR
+        id: build-image
+        env:
+          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
+          IMAGE_TAG: latest
+        run: |
+          docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
+          docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
+          echo "image=$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG" >> $GITHUB_OUTPUT
+
+      - name: Force ECS deployment
+        run: |
+          aws ecs update-service \
+            --cluster ${{ env.ECS_CLUSTER }} \
+            --service ${{ env.ECS_SERVICE }} \
+            --force-new-deployment \
+            --region ${{ env.AWS_REGION }}

package/templates/terraform/backend.tf

@@ -0,0 +1,9 @@
+terraform {
+  backend "s3" {
+    bucket       = "{{STATE_BUCKET}}"
+    key          = "state/terraform.tfstate"
+    region       = "{{REGION}}"
+    encrypt      = true
+    use_lockfile = true
+  }
+}

package/templates/terraform/cloudfront.tf

@@ -0,0 +1,58 @@
+# Fetch the AWS Managed Cache Policy (Optimized for standard web traffic)
+data "aws_cloudfront_cache_policy" "optimized" {
+  name = "Managed-CachingOptimized"
+}
+
+# Fetch the AWS Managed Origin Request Policy (Passes query strings/cookies to your app)
+data "aws_cloudfront_origin_request_policy" "all_viewer" {
+  name = "Managed-AllViewerExceptHostHeader"
+}
+
+resource "aws_cloudfront_distribution" "cdn" {
+  enabled             = true
+  is_ipv6_enabled     = true
+  wait_for_deployment = false # Prevents Terraform from hanging for 10+ minutes
+  
+  origin {
+    # Point the CDN at the Load Balancer we provision in main.tf
+    domain_name = aws_lb.main.dns_name
+    origin_id   = "ALBOrigin"
+
+    custom_origin_config {
+      http_port              = 80
+      https_port             = 443
+      # Because this is the free tier without a custom SSL domain, we route internally via HTTP
+      origin_protocol_policy = "http-only" 
+      origin_ssl_protocols   = ["TLSv1.2"]
+    }
+  }
+
+  default_cache_behavior {
+    # Allow all HTTP methods so API POST/PUT requests still work
+    allowed_methods  = ["DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT"]
+    cached_methods   = ["GET", "HEAD"]
+    target_origin_id = "ALBOrigin"
+
+    viewer_protocol_policy = "redirect-to-https"
+
+    # Attach the Managed Policies
+    cache_policy_id          = data.aws_cloudfront_cache_policy.optimized.id
+    origin_request_policy_id = data.aws_cloudfront_origin_request_policy.all_viewer.id
+  }
+
+  restrictions {
+    geo_restriction {
+      restriction_type = "none"
+    }
+  }
+
+  viewer_certificate {
+    # Gives the user a free HTTPS *.cloudfront.net domain out of the box
+    cloudfront_default_certificate = true
+  }
+}
+
+output "cloudfront_url" {
+  description = "Your globally cached, HTTPS-secured application URL"
+  value       = "https://${aws_cloudfront_distribution.cdn.domain_name}"
+}

package/templates/terraform/main.tf

@@ -0,0 +1,186 @@
+# deploy-stack generated infrastructure
+provider "aws" {
+  region = "{{REGION}}"
+}
+
+locals {
+  # Safely read the keys generated by the CLI, default to empty list if file doesn't exist
+  secret_keys = fileexists("${path.module}/secret_keys.json") ? jsondecode(file("${path.module}/secret_keys.json")) : []
+}
+
+# --- CloudWatch Logs ---
+resource "aws_cloudwatch_log_group" "app_logs" {
+  name              = "/ecs/{{PROJECT_NAME}}"
+  retention_in_days = 14
+}
+
+# --- ECR Repository ---
+resource "aws_ecr_repository" "app" {
+  name                 = "{{PROJECT_NAME}}-repo"
+  image_tag_mutability = "MUTABLE"
+  force_delete         = true
+}
+
+# --- IAM: Execution Role ---
+# Allows the underlying AWS Fargate agent to pull images and push logs
+data "aws_iam_policy_document" "ecs_trust" {
+  statement {
+    actions = ["sts:AssumeRole"]
+    principals {
+      type        = "Service"
+      identifiers = ["ecs-tasks.amazonaws.com"]
+    }
+  }
+}
+
+resource "aws_iam_role" "execution_role" {
+  name               = "{{PROJECT_NAME}}-execution-role"
+  assume_role_policy = data.aws_iam_policy_document.ecs_trust.json
+}
+
+resource "aws_iam_role_policy_attachment" "execution_role_policy" {
+  role       = aws_iam_role.execution_role.name
+  policy_arn = "arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy"
+}
+
+# --- IAM: Task Role ---
+# Allows your application code running INSIDE the container to access AWS services
+resource "aws_iam_role" "task_role" {
+  name               = "{{PROJECT_NAME}}-task-role"
+  assume_role_policy = data.aws_iam_policy_document.ecs_trust.json
+}
+
+# --- ECS Cluster ---
+resource "aws_ecs_cluster" "main" {
+  name = "{{PROJECT_NAME}}-cluster"
+}
+
+# --- ECS Task Definition ---
+resource "aws_ecs_task_definition" "app" {
+  family                   = "{{PROJECT_NAME}}-task"
+  network_mode             = "awsvpc"
+  requires_compatibilities = ["FARGATE"]
+  cpu                      = "{{CPU}}"
+  memory                   = "{{MEMORY}}"
+  execution_role_arn       = aws_iam_role.execution_role.arn
+  task_role_arn            = aws_iam_role.task_role.arn
+
+  container_definitions = jsonencode([
+    {
+      name      = "{{PROJECT_NAME}}-container"
+      image     = "${aws_ecr_repository.app.repository_url}:latest"
+      essential = true
+
+      # Dynamically map every secret key found in the local JSON file
+      secrets = [
+        for key in local.secret_keys : {
+          name      = key
+          valueFrom = "${aws_secretsmanager_secret.app_secrets.arn}:${key}::"
+        }
+      ]
+
+      portMappings = [
+        {
+          containerPort = {{PORT}}
+          hostPort      = {{PORT}}
+          protocol      = "tcp"
+        }
+      ]
+
+      logConfiguration = {
+        logDriver = "awslogs"
+        options = {
+          "awslogs-group"         = aws_cloudwatch_log_group.app_logs.name
+          "awslogs-region"        = "{{REGION}}"
+          "awslogs-stream-prefix" = "ecs"
+        }
+      }
+    }
+  ])
+}
+
+# --- Application Load Balancer ---
+resource "aws_lb" "main" {
+  name               = "{{PROJECT_NAME}}-alb"
+  load_balancer_type = "application"
+  security_groups    = [aws_security_group.alb.id]
+  subnets            = aws_subnet.public[*].id
+}
+
+resource "aws_lb_target_group" "app" {
+  name        = "{{PROJECT_NAME}}-tg"
+  port        = {{PORT}}
+  protocol    = "HTTP"
+  vpc_id      = aws_vpc.main.id
+  target_type = "ip"
+
+  health_check {
+    path                = "{{HEALTH_CHECK_PATH}}"
+    matcher             = "200-399"
+    interval            = 30
+    timeout             = 5
+    healthy_threshold   = 2
+    unhealthy_threshold = 3
+  }
+}
+
+resource "aws_lb_listener" "http" {
+  load_balancer_arn = aws_lb.main.arn
+  port              = "80"
+  protocol          = "HTTP"
+
+  default_action {
+    type             = "forward"
+    target_group_arn = aws_lb_target_group.app.arn
+  }
+}
+
+# --- ECS Service ---
+resource "aws_ecs_service" "app" {
+  name            = "{{PROJECT_NAME}}-service"
+  cluster         = aws_ecs_cluster.main.id
+  task_definition = aws_ecs_task_definition.app.arn
+  launch_type     = "FARGATE"
+  desired_count   = {{DESIRED_COUNT}}
+
+  network_configuration {
+    subnets          = aws_subnet.public[*].id
+    security_groups  = [aws_security_group.ecs_tasks.id]
+    assign_public_ip = true 
+  }
+
+  load_balancer {
+    target_group_arn = aws_lb_target_group.app.arn
+    container_name   = "{{PROJECT_NAME}}-container"
+    container_port   = {{PORT}}
+  }
+
+  depends_on = [aws_lb_listener.http]
+}
+
+# Allow the ECS agent to read the specific secret from Secrets Manager
+resource "aws_iam_role_policy" "secrets_policy" {
+  name   = "{{PROJECT_NAME}}-secrets-policy"
+  role   = aws_iam_role.execution_role.id
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect = "Allow"
+        Action = ["secretsmanager:GetSecretValue"]
+        Resource = [aws_secretsmanager_secret.app_secrets.arn]
+      }
+    ]
+  })
+}
+
+# --- Outputs ---
+output "website_url" {
+  description = "The public URL of your load balancer"
+  value       = "http://${aws_lb.main.dns_name}"
+}
+
+output "ecr_repository_url" {
+  description = "The URL of the ECR repository"
+  value       = aws_ecr_repository.app.repository_url
+}

package/templates/terraform/network.tf

@@ -0,0 +1,90 @@
+# --- VPC & Networking ---
+resource "aws_vpc" "main" {
+  cidr_block           = "10.0.0.0/16"
+  enable_dns_hostnames = true
+  enable_dns_support   = true
+
+  tags = {
+    Name = "{{PROJECT_NAME}}-vpc"
+  }
+}
+
+# Fetch available zones in the current region
+data "aws_availability_zones" "available" {
+  state = "available"
+}
+
+resource "aws_internet_gateway" "main" {
+  vpc_id = aws_vpc.main.id
+}
+
+# Create 2 Public Subnets
+resource "aws_subnet" "public" {
+  count                   = 2
+  vpc_id                  = aws_vpc.main.id
+  cidr_block              = cidrsubnet(aws_vpc.main.cidr_block, 8, count.index)
+  availability_zone       = data.aws_availability_zones.available.names[count.index]
+  map_public_ip_on_launch = true
+
+  tags = {
+    Name = "{{PROJECT_NAME}}-public-subnet-${count.index + 1}"
+  }
+}
+
+# Route internet traffic through the Gateway
+resource "aws_route_table" "public" {
+  vpc_id = aws_vpc.main.id
+  route {
+    cidr_block = "0.0.0.0/0"
+    gateway_id = aws_internet_gateway.main.id
+  }
+}
+
+resource "aws_route_table_association" "public" {
+  count          = 2
+  subnet_id      = aws_subnet.public[count.index].id
+  route_table_id = aws_route_table.public.id
+}
+
+# --- Security Groups ---
+# ALB SG: Allow public internet access on HTTP
+resource "aws_security_group" "alb" {
+  name        = "{{PROJECT_NAME}}-alb-sg"
+  description = "Allow inbound HTTP to ALB"
+  vpc_id      = aws_vpc.main.id
+
+  ingress {
+    from_port   = 80
+    to_port     = 80
+    protocol    = "tcp"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+
+  egress {
+    from_port   = 0
+    to_port     = 0
+    protocol    = "-1"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+}
+
+# ECS SG: Allow traffic ONLY from the ALB on the app's specific port
+resource "aws_security_group" "ecs_tasks" {
+  name        = "{{PROJECT_NAME}}-ecs-sg"
+  description = "Allow inbound access from the ALB only"
+  vpc_id      = aws_vpc.main.id
+
+  ingress {
+    from_port       = {{PORT}}
+    to_port         = {{PORT}}
+    protocol        = "tcp"
+    security_groups = [aws_security_group.alb.id]
+  }
+
+  egress {
+    from_port   = 0
+    to_port     = 0
+    protocol    = "-1"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+}

package/templates/terraform/oidc.tf

@@ -0,0 +1,62 @@
+# Fetch GitHub's OIDC certificate thumbprint
+data "tls_certificate" "github" {
+  url = "https://token.actions.githubusercontent.com"
+}
+
+variable "create_oidc_provider" {
+  description = "Set to false if you already have OIDC provider in your AWS account"
+  type        = bool
+  default     = true
+}
+
+# Register GitHub as an Identity Provider in AWS
+resource "aws_iam_openid_connect_provider" "github" {
+  count           = var.create_oidc_provider ? 1 : 0
+  url             = "https://token.actions.githubusercontent.com"
+  client_id_list  = ["sts.amazonaws.com"]
+  thumbprint_list = [data.tls_certificate.github.certificates[0].sha1_fingerprint]
+}
+
+# Reference the Provider (whether newly created or already existing)
+data "aws_iam_openid_connect_provider" "github_existing" {
+  count = var.create_oidc_provider ? 0 : 1
+  url = "https://token.actions.githubusercontent.com"
+}
+
+# Dynamically pick the ARN of the provider based on the variable
+locals {
+  github_provider_arn = var.create_oidc_provider ? aws_iam_openid_connect_provider.github[0].arn : data.aws_iam_openid_connect_provider.github_existing[0].arn
+}
+
+# Create the IAM Role that GitHub Actions will assume
+resource "aws_iam_role" "github_actions" {
+  name = "{{PROJECT_NAME}}-github-actions-role"
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Action = "sts:AssumeRoleWithWebIdentity"
+        Effect = "Allow"
+        Principal = {
+          Federated = local.github_provider_arn
+        }
+        Condition = {
+          StringLike = {
+            # ⚠️ SECURITY: Update "repo:*" to "repo:your-github-username/your-repo-name:*" in production
+            "token.actions.githubusercontent.com:sub" : "repo:*" 
+          }
+          StringEquals = {
+            "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
+          }
+        }
+      }
+    ]
+  })
+}
+
+# Grant the CI/CD pipeline permissions to provision infrastructure
+resource "aws_iam_role_policy_attachment" "github_actions_admin" {
+  role       = aws_iam_role.github_actions.name
+  policy_arn = "arn:aws:iam::aws:policy/AdministratorAccess" 
+}

package/templates/terraform/secrets.tf

@@ -0,0 +1,18 @@
+# --- AWS Secrets Manager ---
+resource "aws_secretsmanager_secret" "app_secrets" {
+  name                    = "{{PROJECT_NAME}}-secrets"
+  description             = "Environment variables for {{PROJECT_NAME}}"
+  recovery_window_in_days = 0 # Allows instant deletion for dev/POC environments
+}
+
+# Initial placeholder secret so the ECS task doesn't fail on first boot
+resource "aws_secretsmanager_secret_version" "app_secrets_initial" {
+  secret_id = aws_secretsmanager_secret.app_secrets.id
+  secret_string = jsonencode({
+    EXAMPLE_API_KEY = "replace_me_in_aws_console_or_cli"
+  })
+
+  lifecycle {
+    ignore_changes = [secret_string]
+  }
+}