stacks-deploy

# Stacks Deployment The deployment workflow for Stacks applications. ## Quick Deploy ```bash buddy deploy ``` Preview the complete environment-aware plan before changing anything: ```bash 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) ```typescript 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 ```bash # 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 ```bash 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