Stacks Deployment
The deployment workflow for Stacks applications.
Quick Deploy
buddy deploy
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 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-23description: 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: MIT5---67# Stacks Deployment89The deployment workflow for Stacks applications.1011## Quick Deploy1213```bash14buddy deploy15```1617## Deployment Prerequisites18191. **AWS credentials configured**: `buddy configure:aws`202. **APP_KEY generated**: `buddy key:generate` (must be colon-separated format)213. **APP_URL set** in `.env`224. **Team configured** in `config/team.ts`2324## Deployment Flow25261. **Validation** — checks APP_KEY format, AWS region, app URL, team config272. **Build** — compiles application for production283. **Infrastructure** — generates CloudFormation template via ts-cloud294. **Deploy** — creates or updates the CloudFormation stack30 - Capabilities: CAPABILITY_IAM, CAPABILITY_NAMED_IAM31 - OnFailure: ROLLBACK32 - Tags: Environment, Project, ManagedBy3334## Deploy Hooks (cloud/deploy-script.ts)3536```typescript37export default {38 beforeDeploy({ environment, region }) {39 // Build assets, run tests, send notifications40 console.log(`Deploying to ${environment} in ${region}`)41 },4243 afterDeploy({ environment, region, outputs }) {44 // Cache warming, smoke tests, database seeding45 console.log('Public IP:', outputs.PublicIp)46 console.log('DNS:', outputs.DNS)47 console.log('Endpoint:', outputs.Endpoint)48 }49}50```5152## Deployment Modes5354### Server Mode (default)55- EC2 instances with ALB56- Best for: full-stack apps, WebSocket support, persistent connections57- Config: `config/cloud.ts` → `mode: 'server'`5859### Serverless Mode60- Lambda + API Gateway + CloudFront61- Best for: API-only, cost optimization, auto-scaling62- Config: `config/cloud.ts` → `mode: 'serverless'`6364## First Deployment Checklist6566```bash67# 1. Configure AWS68buddy configure:aws6970# 2. Generate app key71buddy key:generate7273# 3. Set environment variables74buddy env:set APP_URL https://myapp.com75buddy env:set APP_ENV production7677# 4. Review cloud config78# Edit config/cloud.ts7980# 5. Deploy81buddy deploy82```8384## CLI Commands8586```bash87buddy deploy # deploy to cloud88buddy cloud --diff # preview infrastructure changes before deploying89buddy cloud --ssh # SSH into deployed server90buddy cloud:remove # tear down infrastructure91buddy cloud:cleanup # clean retained resources92```9394## Gotchas95- First deployment creates the CloudFormation stack — subsequent deploys update it96- APP_KEY must be colon-separated format (validated during deployment)97- Default region is `us-east-1` (from AWS_DEFAULT_REGION env)98- `buddy cloud --diff` shows changes BEFORE deploying — always review first99- Deploy hooks run in the deployment process, not on the target server100- For infrastructure details (EC2, Lambda, VPC, etc.), see the `stacks-cloud` skill