Cloud Deployment

On this page 51

Stacks provides first-class cloud deployment support with automated infrastructure provisioning. Deploy your applications to AWS with a single command.

Deploy targets

cloud.provider in config/cloud.ts decides where buddy deploy ships. This page covers the AWS target, which is the default.

`cloud.provider`	Target	Guide
`'aws'` (default)	CloudFormation stack on AWS	This page
`'hetzner'`	A Hetzner Cloud server	Deploy
`'ssh'`	A Linux host you already own	Raspberry Pi

Overview

Stacks Cloud offers:

One-command deployment - Deploy with buddy deploy
Automated infrastructure - AWS resources provisioned automatically
Zero-downtime updates - Rolling deployments with health checks
Automatic scaling - Scale based on demand
Built-in CDN - CloudFront for static assets
SSL/TLS - Automatic certificate management

Quick Start

Prerequisites

AWS account with appropriate permissions
AWS CLI configured (aws configure)
Stacks project initialized

First Deployment

# Deploy to production (the first run provisions the cloud resources)
buddy deploy

Cloud Configuration

// config/cloud.ts
import { defineCloud } from '@stacksjs/config'

export default defineCloud({
  provider: 'aws',

  region: process.env.AWS_REGION || 'us-east-1',

  domain: 'myapp.com',

  compute: {
    type: 'serverless', // 'serverless' | 'container' | 'vm'
    memory: 1024, // MB for Lambda
    timeout: 30, // seconds
  },

  database: {
    type: 'aurora-serverless',
    minCapacity: 0.5,
    maxCapacity: 4,
    autoPause: true,
    pauseAfter: 300, // 5 minutes
  },

  storage: {
    bucket: 'myapp-storage',
    cdn: true,
  },

  cache: {
    type: 'elasticache',
    nodeType: 'cache.t3.micro',
  },

  cdn: {
    enabled: true,
    priceClass: 'PriceClass_100',
    customDomain: true,
  },
})

Deployment Environments

Development

# Deploy to development
buddy deploy --env=development

Staging

# Deploy to staging
buddy deploy --env=staging

Production

# Deploy to production
buddy deploy --env=production

# Or simply
buddy deploy

Infrastructure Components

Compute Options

Serverless (Lambda)

Best for: Variable workloads, cost optimization

compute: {
  type: 'serverless',
  memory: 1024,
  timeout: 30,
  provisioned: 5, // Optional: provisioned concurrency
}

Containers (ECS/Fargate)

Best for: Consistent workloads, long-running processes

compute: {
  type: 'container',
  cpu: 256,
  memory: 512,
  desiredCount: 2,
  minCount: 1,
  maxCount: 10,
}

Virtual Machines (EC2)

Best for: Maximum control, specific requirements

compute: {
  type: 'vm',
  instanceType: 't3.small',
  minInstances: 2,
  maxInstances: 10,
}

Database Options

Aurora Serverless

database: {
  type: 'aurora-serverless',
  engine: 'mysql', // or 'postgres'
  minCapacity: 0.5,
  maxCapacity: 8,
  autoPause: true,
}

RDS

database: {
  type: 'rds',
  engine: 'mysql',
  instanceClass: 'db.t3.small',
  multiAZ: true,
  storage: 100, // GB
}

DynamoDB

database: {
  type: 'dynamodb',
  billingMode: 'PAY_PER_REQUEST',
}

Cache Options

ElastiCache (Redis)

cache: {
  type: 'elasticache',
  engine: 'redis',
  nodeType: 'cache.t3.micro',
  numNodes: 1,
}

DynamoDB Accelerator (DAX)

cache: {
  type: 'dax',
  nodeType: 'dax.t3.small',
}

Storage

storage: {
  bucket: 'myapp-storage',
  versioning: true,
  encryption: true,
  cdn: true,
  cors: [
    {
      allowedOrigins: ['https://myapp.com'],
      allowedMethods: ['GET', 'PUT'],
    },
  ],
}

CDN (CloudFront)

cdn: {
  enabled: true,
  priceClass: 'PriceClass_100', // US, Canada, Europe
  customDomain: true,
  certificate: 'auto', // Automatic ACM certificate
  compression: true,
  http2: true,
}

Domain & SSL

Custom Domain

domain: {
  name: 'myapp.com',
  hostedZone: 'myapp.com',
  certificate: 'auto',
  subdomains: {
    api: 'api.myapp.com',
    cdn: 'cdn.myapp.com',
  },
}

Automatic SSL

Stacks automatically provisions and renews SSL certificates via AWS Certificate Manager.

Environment Variables

Buddy does not ship cloud environment commands yet. Manage your app's environment variables locally (or via your platform's secret store), then redeploy:

# Set a variable in your .env
buddy env:set APP_KEY secret123

# Read a variable back
buddy env:get APP_KEY

Scaling

Auto Scaling

scaling: {
  enabled: true,
  minInstances: 2,
  maxInstances: 20,
  targetCPU: 70, // Scale when CPU > 70%
  targetMemory: 80,
  scaleInCooldown: 300,
  scaleOutCooldown: 60,
}

Manual Scaling

Manual scaling from the CLI is not implemented yet; scaling is configured through config/cloud.ts as shown above.

Monitoring

CloudWatch Integration

monitoring: {
  enabled: true,
  metrics: ['cpu', 'memory', 'requests', 'errors'],
  alarms: {
    errorRate: {
      threshold: 5,
      period: 60,
      notification: 'alerts@myapp.com',
    },
    latency: {
      threshold: 1000, // ms
      period: 60,
      notification: 'alerts@myapp.com',
    },
  },
}

Logs

A buddy cloud:logs command is not implemented yet; view logs in CloudWatch or via your server's journal (e.g. journalctl -u <service> on the deploy target).

Deployments

Zero-Downtime Deployment

# Default deployment (zero-downtime)
buddy deploy

# Skip the confirmation prompt (e.g. in CI)
buddy deploy --yes

Rollback

A buddy cloud:rollback command is not implemented yet; redeploy the previous release to roll back.

Deployment History

# Inspect servers, sites & deploys in the local cloud cockpit
buddy cloud:dashboard

CI/CD Integration

GitHub Actions

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:

      - uses: actions/checkout@v4

      - name: Setup Bun

        uses: oven-sh/setup-bun@v1

      - name: Install dependencies

        run: bun install

      - name: Run tests

        run: bun test

      - name: Deploy

        run: bun run deploy
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

Cost Optimization

Serverless

Use Aurora Serverless with auto-pause
Configure appropriate Lambda memory
Use CloudFront caching effectively

Containers

Use Spot instances for non-critical workloads
Right-size your containers
Implement efficient auto-scaling

General

# Remove cost-heavy resources that can be re-applied later
buddy cloud:optimize-cost

Security

IAM Roles

Stacks creates least-privilege IAM roles automatically.

VPC Configuration

vpc: {
  enabled: true,
  cidr: '10.0.0.0/16',
  privateSubnets: 2,
  publicSubnets: 2,
  natGateway: true,
}

WAF (Web Application Firewall)

waf: {
  enabled: true,
  rules: ['AWSManagedRulesCommonRuleSet', 'AWSManagedRulesKnownBadInputsRuleSet'],
  rateLimit: 1000, // requests per 5 minutes
}

Commands Reference

# Deploy application
buddy deploy

# Show the diff of the current, undeployed cloud changes
buddy cloud:diff

# Add a resource to your cloud (e.g. a jump box)
buddy cloud:add --jump-box

# Inspect servers, sites & deploys in the local cloud cockpit
buddy cloud:dashboard

# Invalidate the CloudFront cache
buddy cloud:invalidate-cache

# Remove cost-heavy resources that can be re-applied later
buddy cloud:optimize-cost

# Destroy infrastructure (alias: buddy undeploy)
buddy cloud:remove

Best Practices

Start small - Begin with serverless, scale as needed
Use staging - Test deployments in staging first
Monitor costs - Review billing regularly
Enable alerts - Set up CloudWatch alarms
Secure secrets - Use environment variables for sensitive data

Deploy - the three deploy targets and the release flow
Raspberry Pi - deploying to a host you already own, over SSH
Configuration - Application configuration
CI/CD - Continuous integration setup
Testing - Test before deploying

Cloud