Web Service

Deploy containerized web services on AWS Fargate with Application Load Balancer for scalable, managed container hosting.

Thunder provides the @thunderso/cdk-webservice package for deploying Docker containers to ECS Fargate with automatic VPC creation, load balancing, and support for Nixpacks to build containers without writing Dockerfiles.

Supported Frameworks

• Next.js
• Nuxt
• TanStack Start
• SvelteKit
• Astro
• NestJS
• Fastify
• Any containerized web application

Container Service Architecture

The container service architecture provides scalable, managed container hosting with load balancing and high availability.

Route 53 handles DNS resolution for custom domains. Application Load Balancer distributes incoming traffic across multiple container instances with health checks and SSL termination. Fargate runs containerized applications without managing servers, providing automatic scaling and high availability.

Container Deployment Pipeline

The container deployment pipeline builds Docker images and deploys them to managed container infrastructure.

GitHub triggers deployments on code changes. CodePipeline orchestrates the workflow while CodeBuild builds Docker images and pushes to ECR. Fargate pulls the latest images and deploys containers with zero-downtime rolling updates.

Quick Start

Deploy your containerized application to AWS Fargate with automatic infrastructure provisioning. This guide covers installation, configuration, and deployment.

Installation

bun add -D tsx @thunderso/cdk-webservice

Basic Setup

mkdir stack && touch stack/index.ts

Configuration

import { Cdk, WebServiceStack, type WebServiceProps } from "@thunderso/cdk-webservice";

const svcProps: WebServiceProps = {
  env: {
    account: 'your-account-id',
    region: 'us-west-2'
  },
  application: 'my-app',
  service: 'web',
  environment: 'production',
};

new WebServiceStack(
  new Cdk.App(),
  `${svcProps.application}-${svcProps.service}-${svcProps.environment}-stack`,
  svcProps
);

Deploy

bunx cdk deploy --all --app="bunx tsx stack/index.ts"

Custom Domain Setup

Connect your service to a custom domain using Route 53 and ACM certificates. The certificate must be issued in the same region as your Fargate service.

const svcProps: WebServiceProps = {
  // ... other props
  domain: 'app.example.com',
  hostedZoneId: 'Z1D633PJN98FT9',
  regionalCertificateArn: 'arn:aws:acm:us-west-2:123456789012:certificate/abcd1234-abcd-1234-abcd-1234abcd1234',
};

Service Configuration

Container Settings

Configure CPU, memory, desired task count, and container port. Supports ARM64 architecture for better price-performance with Graviton processors.

import { CpuArchitecture } from 'aws-cdk-lib/aws-ecs';

const svcProps: WebServiceProps = {
  // ... other props
  serviceProps: {
    dockerFile: 'Dockerfile',
    architecture: CpuArchitecture.ARM64,
    desiredCount: 2,
    cpu: 512,
    memorySize: 1024,
    port: 3000,
  },
};

Environment Variables

Manage configuration with plain environment variables and secure secrets from AWS Secrets Manager. The library automatically grants ECS tasks permissions to read specified secrets.

const svcProps: WebServiceProps = {
  // ... other props
  serviceProps: {
    variables: [
      { NODE_ENV: 'production' },
      { PUBLIC_API_URL: 'https://api.example.com' }
    ],
    secrets: [
      {
        key: 'DATABASE_URL',
        resource: 'arn:aws:secretsmanager:us-west-2:123456789012:secret:db-url-abc123'
      }
    ],
  },
};

Nixpacks Integration

Use Nixpacks to automatically generate Dockerfiles and build containers without manual configuration. Nixpacks detects your framework and creates optimized builds for Node.js, Python, Go, Rust, and more.

const svcProps: WebServiceProps = {
  // ... other props
  buildProps: {
    buildSystem: 'Nixpacks',
    installcmd: 'bun install',
    buildcmd: 'bun run build',
    startcmd: 'bun start',
    environment: [
      { NODE_ENV: 'production' }
    ],
  },
};

Docker Example

Manually define your container build process with a custom Dockerfile.

# Dockerfile
FROM public.ecr.aws/docker/library/alpine

ENV NODE_ENV=production

# Install Bun
RUN curl -fsSL https://bun.sh/install | bash

# Update PATH for bun
ENV PATH="/root/.bun/bin:$PATH"

# Copy code, install and build
WORKDIR /app
COPY . .
RUN bun install
RUN bun run build

EXPOSE 3000
CMD ["bun", "start"]