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
- Validates APP_KEY format (colon-separated)
- Checks AWS region and credentials
- Validates app URL, name, team configuration
- Creates
InfrastructureGenerator from cloud config
- Generates CloudFormation template
- 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 deleteParameterStore()
await deleteVpcs()
await deleteCdkRemnants()
await deleteIamUsers()
await deleteSubnets()
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
1---2name: stacks-cloud-43description: 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/.4license: MIT5compatibility: Bun >= 1.3.0, TypeScript, AWS6allowed-tools: Read Edit Write Bash Grep Glob7metadata:8 source: https://skillmd.com/skills/stacksjs/stacks-cloud-49---1011# Stacks Cloud & Deployment1213AWS-focused cloud deployment using CloudFormation via `@stacksjs/ts-cloud`.1415## Key Paths16- Cloud package: `storage/framework/core/cloud/src/`17- Deploy package: `storage/framework/core/deploy/`18- CDK stacks: `storage/framework/cloud/` (deploy.ts, cdk.json, package.json)19- Cloud config: `cloud/` (serverless.ts, servers.ts, deploy-script.ts)20- Cloud driver state: `storage/cloud/` (ts-cloud's `stateDir`, set in `config/cloud.ts`)21- Configuration: `config/cloud.ts`2223## Deployment Modes2425### Server Mode (EC2)26- EC2 instances with configurable types (t3.micro, t4g.nano, etc.)27- Application Load Balancer (ALB)28- VPC with public/private subnets29- Security groups with firewall rules30- Auto-scaling capabilities31- SQLite database on instance32- Docker support via Dockerfile3334### Serverless Mode (Lambda)35- Lambda functions for API36- API Gateway (REST/WebSocket)37- CloudFront CDN for static assets38- S3 buckets (frontend, docs, logs, assets)39- SQS queues for background jobs40- DynamoDB (optional)4142## Deployment Flow4344```bash45buddy deploy # deploy to cloud46```47481. Validates APP_KEY format (colon-separated)492. Checks AWS region and credentials503. Validates app URL, name, team configuration514. Creates `InfrastructureGenerator` from cloud config525. Generates CloudFormation template536. Creates or updates stack with:54 - Capabilities: `CAPABILITY_IAM`, `CAPABILITY_NAMED_IAM`55 - Tags: Environment, Project, ManagedBy56 - OnFailure: ROLLBACK5758## Cloud Helper Functions5960```typescript61import { getSecurityGroupId, purchaseDomain, hasBeenDeployed, isFirstDeployment, isFailedState } from '@stacksjs/cloud'6263// Domain management64await purchaseDomain('example.com', { years: 1, privacy: true, autoRenew: true })6566// Infrastructure queries67const sgId = await getSecurityGroupId('my-sg')68const jumpBoxId = await getJumpBoxInstanceId('stack-name')69const deployed = await hasBeenDeployed()70const firstDeploy = await isFirstDeployment()71const failed = await isFailedState()7273// Resource management74await addJumpBox('stack-name')75await deleteJumpBox('stack-name')76await deleteEc2Instance(instanceId, 'stack-name')7778// Cleanup79await deleteStacksBuckets()80await deleteStacksFunctions()81await deleteLogGroups()82await deleteParameterStore()83await deleteVpcs()84await deleteCdkRemnants()85await deleteIamUsers()86await deleteSubnets()87```8889## DNS Functions (AWS Route53)9091```typescript92import { createHostedZone, deleteHostedZone, findHostedZone, getNameservers, updateNameservers } from '@stacksjs/cloud'9394const zone = await createHostedZone('example.com')95const zoneId = await findHostedZone('example.com')96const ns = await getNameservers('example.com')97const hostedNs = await getHostedZoneNameservers('example.com')98await updateNameservers(hostedNs, 'example.com')99await deleteHostedZoneRecords('example.com')100await writeNameserversToConfig(nameservers)101```102103## Server Configuration (cloud/servers.ts)104105```typescript106export default [107 {108 name: 'app-server-1',109 domain: 'stacksjs.com',110 region: 'us-east-1',111 type: 'app', // 'app' | 'web' | 'cache' | 'worker' | 'search'112 instance: 't3.micro',113 disk: 20, // GB114 os: 'ubuntu-20-lts-x86_64',115 bun: '1.1.26',116 database: { type: 'sqlite', name: 'stacks' }117 },118 // ... more servers119]120```121122## Deploy Hooks (cloud/deploy-script.ts)123124```typescript125export default {126 beforeDeploy({ environment, region }) {127 // Pre-deployment: build assets, validate, notify128 },129 afterDeploy({ environment, region, outputs }) {130 // Post-deployment: cache warming, smoke tests, database seeding131 console.log('Public IP:', outputs.PublicIp)132 console.log('DNS:', outputs.DNS)133 }134}135```136137## CLI Commands138139```bash140buddy deploy # deploy application141buddy cloud --diff # show infrastructure changes142buddy cloud --ssh # SSH into cloud143buddy cloud --invalidate-cache # invalidate CDN144buddy cloud:add --jump-box # add jump box instance145buddy cloud:remove --force # destroy cloud resources146buddy cloud:cleanup # clean retained resources147buddy cloud:optimize-cost # remove optional resources148buddy domains:purchase <domain> # purchase domain via Route53149buddy domains:add <domain> # add existing domain150buddy domains:remove <domain> # remove domain151```152153## config/cloud.ts154155```typescript156{157 project: { name: 'my-app', slug: 'my-app', region: 'us-east-1' },158 mode: 'server', // 'server' | 'serverless'159 environments: {160 production: { domain: 'app.com', region: 'us-east-1' },161 staging: { domain: 'staging.app.com' }162 },163 infrastructure: {164 compute: { type: 't3.micro', spot: false },165 loadBalancer: { enabled: true, type: 'application' },166 ssl: { enabled: true },167 dns: { provider: 'route53' },168 storage: { buckets: [] },169 cdn: { enabled: true },170 cache: { enabled: false },171 queue: { enabled: false }172 }173}174```175176## Infrastructure Stack (storage/framework/cloud/)177178- `deploy.ts` — Main deployment script (CDK app entry)179- `cdk.json` — CDK configuration with 54 AWS context settings180- `package.json` — Cloud package dependencies181182Stack naming: `{slugified-app-name}-cloud`183184## Gotchas185- AWS credentials MUST be configured (`buddy configure:aws` or env vars)186- Default region is `us-east-1` (from AWS_DEFAULT_REGION env)187- APP_KEY must be colon-separated format (validated during deployment)188- Server mode uses EC2 + ALB; serverless uses Lambda + API Gateway + CloudFront189- Jump boxes are optional — used for SSH access to private instances190- `cloud:remove` with `--force` skips confirmation — destructive operation191- CDK toolkit stack is named `stacks-toolkit`192- Environment mapping: `local` → `development`, others preserved193- Deploy hooks run before/after deployment for custom logic194- The cloud package has its own `package.json` with framework dependencies