stacks-cloud

# 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 ```bash 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 ```typescript 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) ```typescript 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) ```typescript 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) ```typescript 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 ```bash 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 ```typescript { 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