stacks-cloud

name	stacks-cloud
description	Use when deploying or managing cloud infrastructure for Stacks — AWS deployment via CloudFormation/CDK, server mode (EC2, ALB, VPC), serverless mode (Lambda, API Gateway, CloudFront), jump boxes, domain management (Route53), S3 storage, SES email, edge computing, security groups, IAM, or the cloud configuration. Covers @stacksjs/cloud, @stacksjs/deploy, storage/framework/cloud/, and cloud/.
license	MIT
compatibility	Bun >= 1.3.0, TypeScript, AWS
allowed-tools	Read Edit Write Bash Grep Glob

Stacks Cloud & Deployment

AWS-focused cloud deployment using CloudFormation via @stacksjs/ts-cloud.

Key Paths

• Cloud package: storage/framework/core/cloud/src/
• Deploy package: storage/framework/core/deploy/
• CDK stacks: storage/framework/cloud/ (deploy.ts, cdk.json, package.json)
• Cloud config: cloud/ (serverless.ts, servers.ts, deploy-script.ts)
• Cloud driver state: storage/cloud/ (ts-cloud's stateDir, set in config/cloud.ts)
• Configuration: config/cloud.ts

Deployment Modes

Server Mode (EC2)

• EC2 instances with configurable types (t3.micro, t4g.nano, etc.)
• Application Load Balancer (ALB)
• VPC with public/private subnets
• Security groups with firewall rules
• Auto-scaling capabilities
• SQLite database on instance
• Docker support via Dockerfile

Serverless Mode (Lambda)

• Lambda functions for API
• API Gateway (REST/WebSocket)
• CloudFront CDN for static assets
• S3 buckets (frontend, docs, logs, assets)
• SQS queues for background jobs
• DynamoDB (optional)

Deployment Flow

buddy deploy                    # deploy to cloud

1. Validates APP_KEY format (colon-separated)
2. Checks AWS region and credentials
3. Validates app URL, name, team configuration
4. Creates InfrastructureGenerator from cloud config
5. Generates CloudFormation template
6. Creates or updates stack with:
   • Capabilities: CAPABILITY_IAM, CAPABILITY_NAMED_IAM
   • Tags: Environment, Project, ManagedBy
   • OnFailure: ROLLBACK

Cloud Helper Functions

import { getSecurityGroupId, purchaseDomain, hasBeenDeployed, isFirstDeployment, isFailedState } from '@stacksjs/cloud'

// Domain management
await purchaseDomain('example.com', { years: 1, privacy: true, autoRenew: true })

// Infrastructure queries
const sgId = await getSecurityGroupId('my-sg')
const jumpBoxId = await getJumpBoxInstanceId('stack-name')
const deployed = await hasBeenDeployed()
const firstDeploy = await isFirstDeployment()
const failed = await isFailedState()

// Resource management
await addJumpBox('stack-name')
await deleteJumpBox('stack-name')
await deleteEc2Instance(instanceId, 'stack-name')

// Cleanup
await deleteStacksBuckets()
await deleteStacksFunctions()
await deleteLogGroups()
await ()
 ()
 ()
 ()
 ()

DNS Functions (AWS Route53)

import { createHostedZone, deleteHostedZone, findHostedZone, getNameservers, updateNameservers } from '@stacksjs/cloud'

const zone = await createHostedZone('example.com')
const zoneId = await findHostedZone('example.com')
const ns = await getNameservers('example.com')
const hostedNs = await getHostedZoneNameservers('example.com')
await updateNameservers(hostedNs, 'example.com')
await deleteHostedZoneRecords('example.com')
await writeNameserversToConfig(nameservers)

Server Configuration (cloud/servers.ts)

export default [
  {
    name: 'app-server-1',
    domain: 'stacksjs.com',
    region: 'us-east-1',
    type: 'app',              // 'app' | 'web' | 'cache' | 'worker' | 'search'
    instance: 't3.micro',
    disk: 20,                  // GB
    os: 'ubuntu-20-lts-x86_64',
    bun: '1.1.26',
    database: { type: 'sqlite', name: 'stacks' }
  },
  // ... more servers
]

Deploy Hooks (cloud/deploy-script.ts)

export default {
  beforeDeploy({ environment, region }) {
    // Pre-deployment: build assets, validate, notify
  },
  afterDeploy({ environment, region, outputs }) {
    // Post-deployment: cache warming, smoke tests, database seeding
    console.log('Public IP:', outputs.PublicIp)
    console.log('DNS:', outputs.DNS)
  }
}

CLI Commands

buddy deploy                          # deploy application
buddy cloud --diff                    # show infrastructure changes
buddy cloud --ssh                     # SSH into cloud
buddy cloud --invalidate-cache        # invalidate CDN
buddy cloud:add --jump-box            # add jump box instance
buddy cloud:remove --force            # destroy cloud resources
buddy cloud:cleanup                   # clean retained resources
buddy cloud:optimize-cost             # remove optional resources
buddy domains:purchase <domain>       # purchase domain via Route53
buddy domains:add <domain>            # add existing domain
buddy domains:remove <domain>         # remove domain

config/cloud.ts

{
  project: { name: 'my-app', slug: 'my-app', region: 'us-east-1' },
  mode: 'server',             // 'server' | 'serverless'
  environments: {
    production: { domain: 'app.com', region: 'us-east-1' },
    staging: { domain: 'staging.app.com' }
  },
  infrastructure: {
    compute: { type: 't3.micro', spot: false },
    loadBalancer: { enabled: true, type: 'application' },
    ssl: { enabled: true },
    dns: { provider: 'route53' },
    storage: { buckets: [] },
    cdn: { enabled: true },
    cache: { enabled: false },
    queue: { enabled: false }
  }
}

Infrastructure Stack (storage/framework/cloud/)

• deploy.ts — Main deployment script (CDK app entry)
• cdk.json — CDK configuration with 54 AWS context settings
• package.json — Cloud package dependencies

Stack naming: {slugified-app-name}-cloud

Gotchas

• AWS credentials MUST be configured (buddy configure:aws or env vars)
• Default region is us-east-1 (from AWS_DEFAULT_REGION env)
• APP_KEY must be colon-separated format (validated during deployment)
• Server mode uses EC2 + ALB; serverless uses Lambda + API Gateway + CloudFront
• Jump boxes are optional — used for SSH access to private instances
• cloud:remove with --force skips confirmation — destructive operation
• CDK toolkit stack is named stacks-toolkit
• Environment mapping: local → development, others preserved
• Deploy hooks run before/after deployment for custom logic
• The cloud package has its own package.json with framework dependencies