---
title: Web Service
description: Deploy containerized applications using Fargate and ALB
---
import { Icon } from 'astro-icon/components';
import WebServiceArchitecture from '@/components/docs/patterns/WebServiceArchitecture.astro';
Deploy containerized web services on AWS Fargate with Application Load Balancer for scalable, managed container hosting.
Thunder provides the [@thunderso/cdk-webservice](https://github.com/thunder-so/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](https://nextjs.org/)
- [Nuxt](https://nuxt.com/)
- [TanStack Start](https://tanstack.com/start/latest)
- [SvelteKit](https://kit.svelte.dev/)
- [Astro](https://astro.build/)
- [NestJS](https://nestjs.com/)
- [Fastify](https://www.fastify.io/)
- Any containerized web application
## Container Service Architecture
The container service architecture provides scalable, managed container hosting with load balancing 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
```bash
bun add -D tsx @thunderso/cdk-webservice
```
### Basic Setup
```bash
mkdir stack && touch stack/index.ts
```
### Configuration
```ts
// stack/index.ts
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
```bash
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.
```ts
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.
```ts
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.
```ts
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](https://nixpacks.com/) 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.
```ts
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
# 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"]
```