Stacks Deployment
The deployment workflow for Stacks applications.
Quick Deploy
buddy deploy
Preview the complete environment-aware plan before changing anything:
buddy deploy --dry-run
buddy deploy --dry-run --env staging
buddy deploy --dry-run --site docs
buddy deploy --dry-run --json
The preview uses the same environment transformation and ts-cloud site
classification as a real deploy. It reports the ordered validation,
infrastructure, build, package, release, runtime, gateway, DNS, TLS, and
optional container operations. It exits before prerequisite setup, builds,
packaging, hooks, provider calls, persistence, DNS, TLS, or service restarts.
The JSON form emits a versioned STACKS_DEPLOY_PREVIEW_JSON= line for API and
tool consumers.
Deployment Prerequisites
- AWS credentials configured:
buddy configure:aws
- APP_KEY generated:
buddy key:generate (must be colon-separated format)
- APP_URL set in
.env
- Team configured in
config/team.ts
Deployment Flow
- Validation — checks APP_KEY format, AWS region, app URL, team config
- Build — compiles application for production
- Infrastructure — generates CloudFormation template via ts-cloud
- Deploy — creates or updates the CloudFormation stack
- Capabilities: CAPABILITY_IAM, CAPABILITY_NAMED_IAM
- OnFailure: ROLLBACK
- Tags: Environment, Project, ManagedBy
Deploy Hooks (cloud/deploy-script.ts)
export default {
beforeDeploy({ environment, region }) {
// Build assets, run tests, send notifications
console.log(`Deploying to ${environment} in ${region}`)
},
afterDeploy({ environment, region, outputs }) {
// Cache warming, smoke tests, database seeding
console.log('Public IP:', outputs.PublicIp)
console.log('DNS:', outputs.DNS)
console.log('Endpoint:', outputs.Endpoint)
}
}
Deployment Modes
Server Mode (default)
- EC2 instances with ALB
- Best for: full-stack apps, WebSocket support, persistent connections
- Config:
config/cloud.ts → mode: 'server'
Serverless Mode
- Lambda + API Gateway + CloudFront
- Best for: API-only, cost optimization, auto-scaling
- Config:
config/cloud.ts → mode: 'serverless'
First Deployment Checklist
# 1. Configure AWS
buddy configure:aws
# 2. Generate app key
buddy key:generate
# 3. Set environment variables
buddy env:set APP_URL https://myapp.com
buddy env:set APP_ENV production
# 4. Review cloud config
# Edit config/cloud.ts
# 5. Deploy
buddy deploy
CLI Commands
buddy deploy # deploy to cloud
buddy deploy --dry-run # preview without changing anything
buddy cloud --diff # preview infrastructure changes before deploying
buddy cloud --ssh # SSH into deployed server
buddy cloud:remove # tear down infrastructure
buddy cloud:cleanup # clean retained resources
Gotchas
- First deployment creates the CloudFormation stack — subsequent deploys update it
- APP_KEY must be colon-separated format (validated during deployment)
- Default region is
us-east-1 (from AWS_DEFAULT_REGION env)
buddy cloud --diff shows changes BEFORE deploying — always review first
- Deploy hooks run in the deployment process, not on the target server
- For infrastructure details (EC2, Lambda, VPC, etc.), see the
stacks-cloud skill
1---2name: stacks-deploy-43description: Use when deploying a Stacks application - the deployment workflow (build → deploy), pre/post deploy hooks, server vs serverless mode selection, first-time deployment setup, deployment troubleshooting, or the buddy deploy command. For cloud infrastructure details (EC2, Lambda, CloudFormation, Route53, IAM), see stacks-cloud.4license: MIT5compatibility: Bun >= 1.3.0, TypeScript, AWS6allowed-tools: Read Edit Write Bash Grep Glob7metadata:8 source: https://skillmd.com/skills/stacksjs/stacks-deploy-49---1011# Stacks Deployment1213The deployment workflow for Stacks applications.1415## Quick Deploy1617```bash18buddy deploy19```2021Preview the complete environment-aware plan before changing anything:2223```bash24buddy deploy --dry-run25buddy deploy --dry-run --env staging26buddy deploy --dry-run --site docs27buddy deploy --dry-run --json28```2930The preview uses the same environment transformation and ts-cloud site31classification as a real deploy. It reports the ordered validation,32infrastructure, build, package, release, runtime, gateway, DNS, TLS, and33optional container operations. It exits before prerequisite setup, builds,34packaging, hooks, provider calls, persistence, DNS, TLS, or service restarts.35The JSON form emits a versioned `STACKS_DEPLOY_PREVIEW_JSON=` line for API and36tool consumers.3738## Deployment Prerequisites39401. **AWS credentials configured**: `buddy configure:aws`412. **APP_KEY generated**: `buddy key:generate` (must be colon-separated format)423. **APP_URL set** in `.env`434. **Team configured** in `config/team.ts`4445## Deployment Flow46471. **Validation** — checks APP_KEY format, AWS region, app URL, team config482. **Build** — compiles application for production493. **Infrastructure** — generates CloudFormation template via ts-cloud504. **Deploy** — creates or updates the CloudFormation stack51 - Capabilities: CAPABILITY_IAM, CAPABILITY_NAMED_IAM52 - OnFailure: ROLLBACK53 - Tags: Environment, Project, ManagedBy5455## Deploy Hooks (cloud/deploy-script.ts)5657```typescript58export default {59 beforeDeploy({ environment, region }) {60 // Build assets, run tests, send notifications61 console.log(`Deploying to ${environment} in ${region}`)62 },6364 afterDeploy({ environment, region, outputs }) {65 // Cache warming, smoke tests, database seeding66 console.log('Public IP:', outputs.PublicIp)67 console.log('DNS:', outputs.DNS)68 console.log('Endpoint:', outputs.Endpoint)69 }70}71```7273## Deployment Modes7475### Server Mode (default)76- EC2 instances with ALB77- Best for: full-stack apps, WebSocket support, persistent connections78- Config: `config/cloud.ts` → `mode: 'server'`7980### Serverless Mode81- Lambda + API Gateway + CloudFront82- Best for: API-only, cost optimization, auto-scaling83- Config: `config/cloud.ts` → `mode: 'serverless'`8485## First Deployment Checklist8687```bash88# 1. Configure AWS89buddy configure:aws9091# 2. Generate app key92buddy key:generate9394# 3. Set environment variables95buddy env:set APP_URL https://myapp.com96buddy env:set APP_ENV production9798# 4. Review cloud config99# Edit config/cloud.ts100101# 5. Deploy102buddy deploy103```104105## CLI Commands106107```bash108buddy deploy # deploy to cloud109buddy deploy --dry-run # preview without changing anything110buddy cloud --diff # preview infrastructure changes before deploying111buddy cloud --ssh # SSH into deployed server112buddy cloud:remove # tear down infrastructure113buddy cloud:cleanup # clean retained resources114```115116## Gotchas117- First deployment creates the CloudFormation stack — subsequent deploys update it118- APP_KEY must be colon-separated format (validated during deployment)119- Default region is `us-east-1` (from AWS_DEFAULT_REGION env)120- `buddy cloud --diff` shows changes BEFORE deploying — always review first121- Deploy hooks run in the deployment process, not on the target server122- For infrastructure details (EC2, Lambda, VPC, etc.), see the `stacks-cloud` skill