mysystem-cli 1.0.0 → 1.0.2

package/templates/github/deploy-ec2.yml

@@ -0,0 +1,163 @@
+name: MySystem EC2 Deployment
+
+on:
+  push:
+    branches:
+      - main
+      - master
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  deploy:
+    name: Deploy to AWS EC2 (Hobbyist Tier)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      # --- Step 1: Parse MySystem Config File ---
+      - name: Parse MySystem Config
+        id: config
+        run: |
+          echo "APP_NAME=$(jq -r .name mysystem.json)" >> $GITHUB_ENV
+          echo "AWS_REGION=$(jq -r .region mysystem.json)" >> $GITHUB_ENV
+          echo "CONTAINER_PORT=$(jq -r .port mysystem.json)" >> $GITHUB_ENV
+          echo "BILLING_EMAIL=$(jq -r .billingEmail mysystem.json)" >> $GITHUB_ENV
+          echo "ENABLE_CUSTOM_DOMAIN=$(jq -r .customDomain mysystem.json)" >> $GITHUB_ENV
+          echo "DOMAIN_NAME=$(jq -r .domainName mysystem.json)" >> $GITHUB_ENV
+          echo "DNS_PROVIDER=$(jq -r .dnsProvider mysystem.json)" >> $GITHUB_ENV
+
+      # --- Step 2: Authenticate with AWS via OIDC ---
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
+          aws-region: ${{ env.AWS_REGION }}
+          audience: sts.amazonaws.com
+
+      # --- Step 3: Provision EC2 & ECR via Terraform ---
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_version: 1.6.0
+
+      - name: Terraform Init & Apply
+        working-directory: ./terraform
+        env:
+          TF_VAR_aws_region: ${{ env.AWS_REGION }}
+          TF_VAR_app_name: ${{ env.APP_NAME }}
+          TF_VAR_container_port: ${{ env.CONTAINER_PORT }}
+          TF_VAR_billing_email: ${{ env.BILLING_EMAIL }}
+          TF_VAR_enable_custom_domain: ${{ env.ENABLE_CUSTOM_DOMAIN }}
+          TF_VAR_domain_name: ${{ env.DOMAIN_NAME }}
+          TF_VAR_dns_provider: ${{ env.DNS_PROVIDER }}
+        run: |
+          terraform init
+          terraform apply -auto-approve
+
+      # --- Step 4: Extract Terraform Outputs ---
+      - name: Get Outputs
+        id: tf_outputs
+        working-directory: ./terraform
+        run: |
+          echo "ECR_REPO=$(terraform output -raw ecr_repository_url)" >> $GITHUB_OUTPUT
+          echo "INSTANCE_ID=$(terraform output -raw instance_id)" >> $GITHUB_OUTPUT
+          echo "APP_URL=$(terraform output -raw application_url)" >> $GITHUB_OUTPUT
+
+      # --- Step 5: Login to Amazon ECR ---
+      - name: Login to Amazon ECR
+        id: login-ecr
+        uses: aws-actions/amazon-ecr-login@v2
+
+      # --- Step 6: Build and Push Docker Image ---
+      - name: Build, Tag, and Push Image to ECR
+        id: build-image
+        env:
+          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
+          ECR_REPOSITORY: ${{ steps.tf_outputs.outputs.ECR_REPO }}
+          IMAGE_TAG: ${{ github.sha }}
+        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
+
+      # --- Step 7: Deploy to EC2 via AWS SSM ---
+      - name: Deploy to EC2 via AWS SSM
+        env:
+          INSTANCE_ID: ${{ steps.tf_outputs.outputs.INSTANCE_ID }}
+          IMAGE_URL: ${{ steps.build-image.outputs.image }}
+          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
+          AWS_DEFAULT_REGION: ${{ env.AWS_REGION }}
+          CONTAINER_PORT: ${{ env.CONTAINER_PORT }}
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+        run: |
+          # Generate a secure password for Postgres
+          DB_PASSWORD=$(openssl rand -base64 12)
+
+          # Write the deployment script
+          cat <<EOF > deploy.sh
+          #!/bin/bash
+          # 1. Login to ECR
+          aws ecr get-login-password --region ${AWS_DEFAULT_REGION} | docker login --username AWS --password-stdin ${ECR_REGISTRY}
+
+          # 2. Create app directory
+          mkdir -p /home/ec2-user/app
+          
+          # 3. Create docker-compose.yml
+          cat <<'COMPOSE' > /home/ec2-user/app/docker-compose.yml
+          version: '3.8'
+          services:
+            web:
+              image: ${IMAGE_URL}
+              restart: always
+              ports:
+                - "80:${CONTAINER_PORT}"
+              environment:
+                - PORT=${CONTAINER_PORT}
+                - NODE_ENV=production
+                - DATABASE_URL=postgresql://mysystem_admin:${DB_PASSWORD}@db:5432/mysystem_db
+                - SENTRY_DSN=${SENTRY_DSN}
+              depends_on:
+                - db
+
+            db:
+              image: postgres:15-alpine
+              restart: always
+              environment:
+                - POSTGRES_USER=mysystem_admin
+                - POSTGRES_PASSWORD=${DB_PASSWORD}
+                - POSTGRES_DB=mysystem_db
+              volumes:
+                - pgdata:/var/lib/postgresql/data
+
+          volumes:
+            pgdata:
+          COMPOSE
+
+          # 4. Pull and run containers
+          cd /home/ec2-user/app
+          docker compose pull
+          docker compose up -d
+          EOF
+
+          # Base64 encode the script to avoid all command-line escaping issues
+          B64_SCRIPT=\$(base64 -w 0 deploy.sh)
+
+          # Send run command to AWS SSM
+          CMD_ID=\$(aws ssm send-command \
+            --instance-ids "${INSTANCE_ID}" \
+            --document-name "AWS-RunShellScript" \
+            --parameters "commands=[\"echo '\$B64_SCRIPT' | base64 -d > /tmp/deploy.sh\", \"chmod +x /tmp/deploy.sh\", \"/tmp/deploy.sh\"]" \
+            --query "Command.CommandId" \
+            --region "${AWS_DEFAULT_REGION}" \
+            --output text)
+
+          echo "Deployment initiated via SSM. Command ID: \$CMD_ID"
+
+      - name: Show App URL
+        run: |
+          echo "🎉 App successfully deployed to: ${{ steps.tf_outputs.outputs.APP_URL }}"

package/templates/github/deploy.yml

@@ -0,0 +1,94 @@
+name: MySystem Deployment
+
+on:
+  push:
+    branches:
+      - main
+      - master
+
+permissions:
+  id-token: write # Required for AWS OIDC authentication
+  contents: read
+
+jobs:
+  deploy:
+    name: Deploy to AWS Fargate
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      # --- Step 1: Authenticate with AWS via OIDC ---
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
+          aws-region: us-east-1 # Will be customized by CLI on setup
+          audience: sts.amazonaws.com
+
+      # --- Step 2: Provision Infrastructure using Terraform ---
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_version: 1.6.0
+
+      - name: Terraform Init & Apply
+        working-directory: ./terraform
+        run: |
+          terraform init
+          terraform apply -auto-approve
+
+      # --- Step 3: Extract Terraform Outputs ---
+      - name: Get Outputs
+        id: tf_outputs
+        working-directory: ./terraform
+        run: |
+          echo "ECR_REPO=$(terraform output -raw ecr_repository_url)" >> $GITHUB_OUTPUT
+          echo "APP_URL=$(terraform output -raw application_url)" >> $GITHUB_OUTPUT
+
+      # --- Step 4: Login to Amazon ECR ---
+      - name: Login to Amazon ECR
+        id: login-ecr
+        uses: aws-actions/amazon-ecr-login@v2
+
+      # --- Step 5: Build and Push Docker Image ---
+      - name: Build, Tag, and Push Image to ECR
+        id: build-image
+        env:
+          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
+          ECR_REPOSITORY: ${{ steps.tf_outputs.outputs.ECR_REPO }}
+          IMAGE_TAG: ${{ github.sha }}
+        run: |
+          # Build a local Docker image
+          docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
+          # Push it to ECR
+          docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
+          # Save image URL as output
+          echo "image=$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG" >> $GITHUB_OUTPUT
+
+      # --- Step 6: Deploy to ECS Fargate ---
+      # This pulls down the task definition template, updates it with the new image, and deploys it.
+      - name: Download Task Definition
+        run: |
+          aws ecs describe-task-definition --task-definition ${{ github.event.repository.name }} --query taskDefinition > task-definition.json
+
+      - name: Fill in the new image ID in the Amazon ECS task definition
+        id: render-task-def
+        uses: aws-actions/amazon-ecs-render-task-definition@v1
+        with:
+          task-definition: task-definition.json
+          container-name: ${{ github.event.repository.name }}
+          image: ${{ steps.build-image.outputs.image }}
+
+      - name: Deploy Amazon ECS task definition
+        uses: aws-actions/amazon-ecs-deploy-task-definition@v2
+        with:
+          task-definition: ${{ steps.render-task-def.outputs.task-definition }}
+          service: ${{ github.event.repository.name }}
+          cluster: ${{ github.event.repository.name }}-cluster
+          wait-for-service-stability: true
+
+      - name: Show App URL
+        run: |
+          echo "🎉 App successfully deployed to: ${{ steps.tf_outputs.outputs.APP_URL }}"

package/templates/github/destroy.yml

@@ -0,0 +1,43 @@
+name: MySystem Teardown (Destroy)
+
+on:
+  workflow_dispatch: # Allows manual trigger from the GitHub Actions UI
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  destroy:
+    name: Teardown AWS Infrastructure
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      # --- Step 1: Authenticate with AWS via OIDC ---
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
+          aws-region: us-east-1 # Will be customized by CLI on setup
+          audience: sts.amazonaws.com
+
+      # --- Step 2: Set up Terraform ---
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_version: 1.6.0
+
+      # --- Step 3: Run Terraform Destroy ---
+      - name: Terraform Init & Destroy
+        working-directory: ./terraform
+        run: |
+          terraform init
+          terraform destroy -auto-approve
+
+      - name: Success Message
+        run: |
+          echo "🔥 All AWS resources for this application have been successfully destroyed."
+          echo "Your AWS billing for this project has been stopped."

package/templates/terraform/alb.tf

@@ -0,0 +1,69 @@
+resource "aws_lb" "main" {
+  name               = "${var.app_name}-alb"
+  internal           = false
+  load_balancer_type = "application"
+  security_groups    = [aws_security_group.alb.id]
+  subnets            = aws_subnet.public[*].id
+
+  tags = {
+    Name = "${var.app_name}-alb"
+  }
+}
+
+resource "aws_lb_target_group" "app" {
+  name        = "${var.app_name}-tg"
+  port        = var.container_port
+  protocol    = "HTTP"
+  vpc_id      = aws_vpc.main.id
+  target_type = "ip"
+
+  health_check {
+    healthy_threshold   = 3
+    unhealthy_threshold = 3
+    timeout             = 5
+    interval            = 30
+    path                = "/health" # Compliant with AGENTS.md rule
+    protocol            = "HTTP"
+    matcher             = "200"
+  }
+
+  tags = {
+    Name = "${var.app_name}-tg"
+  }
+}
+
+# HTTP Listener (Port 80)
+resource "aws_lb_listener" "http" {
+  load_balancer_arn = aws_lb.main.arn
+  port              = "80"
+  protocol          = "HTTP"
+
+  default_action {
+    type             = var.enable_custom_domain ? "redirect" : "forward"
+    target_group_arn = var.enable_custom_domain ? null : aws_lb_target_group.app.arn
+
+    dynamic "redirect" {
+      for_each = var.enable_custom_domain ? [1] : []
+      content {
+        port        = "443"
+        protocol    = "HTTPS"
+        status_code = "HTTP_301"
+      }
+    }
+  }
+}
+
+# HTTPS Listener (Port 443) - Created only if custom domain is enabled
+resource "aws_lb_listener" "https" {
+  count             = var.enable_custom_domain ? 1 : 0
+  load_balancer_arn = aws_lb.main.arn
+  port              = "443"
+  protocol          = "HTTPS"
+  ssl_policy        = "ELBSecurityPolicy-2016-08"
+  certificate_arn   = aws_acm_certificate.cert[0].arn
+
+  default_action {
+    type             = "forward"
+    target_group_arn = aws_lb_target_group.app.arn
+  }
+}

package/templates/terraform/bootstrap-oidc.yaml

@@ -0,0 +1,69 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Description: Bootstrap IAM Role for GitHub Actions OIDC connection to AWS (MySystem).
+
+Parameters:
+  GitHubOrg:
+    Type: String
+    Description: Your GitHub Organization or Username (case-sensitive)
+  GitHubRepo:
+    Type: String
+    Description: Your GitHub Repository Name (case-sensitive)
+
+Resources:
+  # OIDC Provider for GitHub (Created only if it doesn't exist, we assume it's created or we create it here)
+  # Note: Since there can only be one OIDC provider per account, we handle it. If it fails, users can use an existing one.
+  GithubOidcProvider:
+    Type: AWS::IAM::OIDCProvider
+    Properties:
+      Url: https://token.actions.githubusercontent.com
+      ClientIdList:
+        - sts.amazonaws.com
+      ThumbprintList:
+        - 6938fd4d98bab03faadb97b34396831e3780aea1 # GitHub Actions Thumbprint
+
+  # IAM Role that GitHub Actions will assume to deploy the app
+  MySystemDeployRole:
+    Type: AWS::IAM::Role
+    Properties:
+      RoleName: !Sub 'MySystemDeployRole-${GitHubRepo}'
+      Description: IAM Role assumed by GitHub Actions to deploy infrastructure and code.
+      AssumeRolePolicyDocument:
+        Version: '2012-10-17'
+        Statement:
+          - Effect: Allow
+            Principal:
+              Federated: !Ref GithubOidcProvider
+            Action: sts:AssumeRoleWithWebIdentity
+            Condition:
+              StringEquals:
+                token.actions.githubusercontent.com:aud: sts.amazonaws.com
+              StringLike:
+                token.actions.githubusercontent.com:sub: !Sub 'repo:${GitHubOrg}/${GitHubRepo}:*'
+      # Attach Policies to allow Terraform to provision VPC, ECS, RDS, ALB, ECR etc.
+      ManagedPolicyArns:
+        - arn:aws:iam::aws:policy/PowerUserAccess
+      Policies:
+        - PolicyName: MySystemAdditionalIAMPolicy
+          PolicyDocument:
+            Version: '2012-10-17'
+            Statement:
+              # PowerUserAccess does not allow managing IAM roles. Terraform needs to create ECS Task Execution Roles.
+              - Effect: Allow
+                Action:
+                  - iam:CreateRole
+                  - iam:DeleteRole
+                  - iam:GetRole
+                  - iam:PassRole
+                  - iam:PutRolePolicy
+                  - iam:DeleteRolePolicy
+                  - iam:GetRolePolicy
+                  - iam:AttachRolePolicy
+                  - iam:DetachRolePolicy
+                Resource:
+                  - !Sub 'arn:aws:iam::${AWS::AccountId}:role/*-ecs-execution-role'
+                  - !Sub 'arn:aws:iam::${AWS::AccountId}:role/*-ecs-task-role'
+
+Outputs:
+  RoleARN:
+    Description: The ARN of the IAM Role for GitHub Actions. Copy this to your GitHub Repository Secret `AWS_ROLE_ARN`.
+    Value: !GetAtt MySystemDeployRole.Arn

package/templates/terraform/budget.tf

@@ -0,0 +1,40 @@
+# AWS Cost Budget Alert
+# Sends an email notification if the forecasted or actual AWS monthly spend exceeds the specified threshold.
+
+variable "billing_email" {
+  type        = string
+  description = "Email address to send AWS budget and billing alerts"
+  default     = ""
+}
+
+variable "budget_limit" {
+  type        = string
+  description = "Monthly budget limit in USD"
+  default     = "20"
+}
+
+resource "aws_budgets_budget" "monthly_cost" {
+  count             = var.billing_email != "" ? 1 : 0
+  name              = "${var.app_name}-monthly-budget"
+  budget_type       = "COST"
+  limit_amount      = var.budget_limit
+  limit_unit        = "USD"
+  time_period_start = "2026-01-01_00:00" # Arbitrary start date in the past/present
+  time_unit         = "MONTHLY"
+
+  notification {
+    comparison_operator        = "GREATER_THAN"
+    threshold                  = 80
+    threshold_type             = "PERCENTAGE"
+    notification_type          = "ACTUAL"
+    subscriber_email_addresses = [var.billing_email]
+  }
+
+  notification {
+    comparison_operator        = "GREATER_THAN"
+    threshold                  = 100
+    threshold_type             = "PERCENTAGE"
+    notification_type          = "FORECASTED"
+    subscriber_email_addresses = [var.billing_email]
+  }
+}

package/templates/terraform/db.tf

@@ -0,0 +1,46 @@
+resource "random_password" "db_password" {
+  count   = var.enable_database ? 1 : 0
+  length  = 16
+  special = false
+}
+
+resource "aws_db_subnet_group" "main" {
+  count      = var.enable_database ? 1 : 0
+  name       = "${var.app_name}-db-subnet-group"
+  subnet_ids = aws_subnet.private[*].id
+
+  tags = {
+    Name = "${var.app_name}-db-subnet-group"
+  }
+}
+
+resource "aws_db_instance" "postgres" {
+  count                  = var.enable_database ? 1 : 0
+  identifier             = "${var.app_name}-db"
+  allocated_storage      = 20
+  max_allocated_storage  = 100
+  engine                 = "postgres"
+  engine_version         = "15"
+  instance_class         = "db.t4g.micro" # cost-effective burstable Graviton instance
+  db_name                = replace(var.app_name, "-", "_")
+  username               = "mysystem_admin"
+  password               = random_password.db_password[0].result
+  db_subnet_group_name   = aws_db_subnet_group.main[0].name
+  vpc_security_group_ids = [aws_security_group.db[0].id]
+  skip_final_snapshot    = true
+  publicly_accessible    = false
+
+  tags = {
+    Name = "${var.app_name}-db-postgres"
+  }
+}
+
+# Save password in SSM Parameter Store so the developer can retrieve it if needed,
+# and so ECS tasks can fetch it securely.
+resource "aws_ssm_parameter" "db_url" {
+  count       = var.enable_database ? 1 : 0
+  name        = "/${var.app_name}/database_url"
+  type        = "SecureString"
+  description = "Database URL for the application"
+  value       = "postgresql://${aws_db_instance.postgres[0].username}:${random_password.db_password[0].result}@${var.enable_rds_proxy ? aws_db_proxy.postgres[0].endpoint : aws_db_instance.postgres[0].endpoint}/${aws_db_instance.postgres[0].db_name}"
+}

package/templates/terraform/dns.tf

@@ -0,0 +1,89 @@
+# AWS ACM (SSL Certificate) and Custom Domain Routing
+# Supports automated Route 53 setups or external DNS providers (GoDaddy, Cloudflare, Namecheap)
+
+variable "enable_custom_domain" {
+  type        = bool
+  description = "Enable custom domain and HTTPS SSL certificate"
+  default     = false
+}
+
+variable "domain_name" {
+  type        = string
+  description = "The custom domain name (e.g., app.example.com)"
+  default     = ""
+}
+
+variable "dns_provider" {
+  type        = string
+  description = "DNS provider for domain validation ('route53' or 'external')"
+  default     = "external"
+}
+
+# 1. SSL/TLS Certificate via ACM
+resource "aws_acm_certificate" "cert" {
+  count             = var.enable_custom_domain ? 1 : 0
+  domain_name       = var.domain_name
+  validation_method = "DNS"
+
+  lifecycle {
+    create_before_destroy = true
+  }
+
+  tags = {
+    Name = "${var.app_name}-cert"
+  }
+}
+
+# --- Route 53 DNS Configuration (Automated Setup) ---
+data "aws_route53_zone" "primary" {
+  count        = var.enable_custom_domain && var.dns_provider == "route53" ? 1 : 0
+  name         = join(".", slice(split(".", var.domain_name), length(split(".", var.domain_name)) - 2, length(split(".", var.domain_name))))
+  private_zone = false
+}
+
+# Create DNS validation record in Route53
+resource "aws_route53_record" "cert_validation" {
+  count   = var.enable_custom_domain && var.dns_provider == "route53" ? 1 : 0
+  name    = tolist(aws_acm_certificate.cert[0].domain_validation_options)[0].resource_record_name
+  type    = tolist(aws_acm_certificate.cert[0].domain_validation_options)[0].resource_record_type
+  zone_id = data.aws_route53_zone.primary[0].zone_id
+  records = [tolist(aws_acm_certificate.cert[0].domain_validation_options)[0].resource_record_value]
+  ttl     = 60
+}
+
+# Validate certificate in ACM (Wait for validation to complete)
+resource "aws_acm_certificate_validation" "cert" {
+  count                   = var.enable_custom_domain && var.dns_provider == "route53" ? 1 : 0
+  certificate_arn         = aws_acm_certificate.cert[0].arn
+  validation_record_fqdns = [aws_route53_record.cert_validation[0].fqdn]
+}
+
+# Create A record in Route53 pointing to the Load Balancer
+resource "aws_route53_record" "app" {
+  count   = var.enable_custom_domain && var.dns_provider == "route53" ? 1 : 0
+  zone_id = data.aws_route53_zone.primary[0].zone_id
+  name    = var.domain_name
+  type    = "A"
+
+  alias {
+    name                   = aws_lb.main.dns_name
+    zone_id                = aws_lb.main.zone_id
+    evaluate_target_health = true
+  }
+}
+
+# --- Outputs for External DNS Setup (GoDaddy, Cloudflare, etc.) ---
+output "dns_validation_name" {
+  value       = var.enable_custom_domain ? tolist(aws_acm_certificate.cert[0].domain_validation_options)[0].resource_record_name : "None"
+  description = "CNAME Name to add to your DNS provider for SSL certificate validation"
+}
+
+output "dns_validation_value" {
+  value       = var.enable_custom_domain ? tolist(aws_acm_certificate.cert[0].domain_validation_options)[0].resource_record_value : "None"
+  description = "CNAME Value/Alias to add to your DNS provider for SSL certificate validation"
+}
+
+output "app_cname_alias" {
+  value       = aws_lb.main.dns_name
+  description = "Point your domain CNAME record to this target to route traffic to the app"
+}