Skip to content
VentureKit

Deployment

VentureKit applications are deployed to AWS using CDK through the vk CLI.

Prerequisites

Section titled “Prerequisites”
  • AWS credentials configured (aws configure or environment variables)
  • Node.js >= 20
  • VentureKit project initialized with vk init

Development

Section titled “Development”

Start a local development server with hot-reloading:

Terminal window
vk dev

This starts a fully local development server that:

  • Serves your routes via HTTP (no AWS credentials needed)
  • Starts Docker Compose services for Postgres, Redis, and MinIO
  • Loads TypeScript handlers at runtime — no build step

Custom Stage

Section titled “Custom Stage”
Terminal window
vk dev --stage my-dev

Deploying

Section titled “Deploying”

Dev Environment

Section titled “Dev Environment”
Terminal window
vk deploy

Staging

Section titled “Staging”
Terminal window
vk deploy --stage stage

Production

Section titled “Production”
Terminal window
vk deploy --stage prod

Free-Tier Deployment

Section titled “Free-Tier Deployment”

Deploy VentureKit at zero cost using only AWS free-tier services:

config/dev.ts
import type { EnvConfigInput } from '@venturekit/core';


export const dev: EnvConfigInput = {
  preset: 'free',
  dataSafety: 'relaxed',
};

The free preset automatically:

  • Uses Lambda (1M free requests/month) with 128 MB
  • Uses API Gateway HTTP API (1M free calls/month for 12 months)
  • Substitutes DynamoDB for RDS databases (25 GB always-free)
  • Skips VPC and NAT gateways (not free)
  • Skips ElastiCache — uses DynamoDB-based rate limiting instead
  • Uses SQS (1M free requests/month) and EventBridge (free)

Environment Selection

Section titled “Environment Selection”

The VENTURE_STAGE environment variable maps to your config files:

StageConfigTypical Preset
devconfig/dev.tsfree or nano
stageconfig/stage.tsmicro
prodconfig/prod.tsmedium or large
Terminal window
# These are equivalent:
vk deploy --stage prod
VENTURE_STAGE=prod vk deploy

Tearing Down

Section titled “Tearing Down”

Remove deployed resources:

Terminal window
# Remove dev (no confirmation needed)
vk remove


# Remove staging (requires confirmation)
vk remove --stage stage


# Remove production (requires confirmation, skip with --yes)
vk remove --stage prod --yes

CI/CD

Section titled “CI/CD”

GitHub Actions Example

Section titled “GitHub Actions Example”
name: Deploy
on:
  push:
    branches: [main]


jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - uses: pnpm/action-setup@v2
        with:
          version: 9


      - run: pnpm install
      - run: vk deploy --stage prod
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_REGION: eu-west-1

Custom Domains

Section titled “Custom Domains”

Configure a custom domain in your environment config:

export const prod: EnvConfigInput = {
  preset: 'medium',
  api: {
    customDomain: {
      domainName: 'api.example.com',
      certificateArn: 'arn:aws:acm:us-east-1:...',
    },
  },
};

Deploy Outputs

Section titled “Deploy Outputs”

After deployment, the CLI displays:

  • API URL — your API Gateway endpoint
  • WebSocket URL — if WebSocket is enabled
  • Stage and environment information
✅ Deployed to prod


API URL: https://abc123.execute-api.eu-west-1.amazonaws.com