stacks-deploy

name	stacks-deploy
description	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.
license	MIT
compatibility	Bun >= 1.3.0, TypeScript, AWS
allowed-tools	Read Edit Write Bash Grep Glob

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

1. AWS credentials configured: buddy configure:aws
2. APP_KEY generated: buddy key:generate (must be colon-separated format)
3. APP_URL set in .env
4. Team configured in config/team.ts

Deployment Flow

1. Validation — checks APP_KEY format, AWS region, app URL, team config
2. Build — compiles application for production
3. Infrastructure — generates CloudFormation template via ts-cloud
4. 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