Fjall Docs — Deploy Production-Ready AWS Infrastructure in Minutes

Overview

The ComputeFactory is Fjall’s pattern for creating compute resources. It provides a unified interface to deploy different compute types including ECS containers, EC2 instances, and Lambda functions.

Basic Usage

import { App, ComputeFactory } from "@fjall/components-infrastructure";

const app = App.getApp("myapp");

app.addCompute(
  ComputeFactory.build("MyCompute", {
    type: "ecs",
    services: [
      {
        name: "web",
        capacityProvider: "FARGATE",
        cpu: 256,
        memoryLimitMiB: 512,
      },
    ],
  }),
);

Compute Types

ECS (Elastic Container Service)

Deploy containerised applications with three variants:

Fargate (Recommended)

app.addCompute(
  ComputeFactory.build("MyService", {
    type: "ecs",
    services: [
      {
        name: "api",
        capacityProvider: "FARGATE",
        cpu: 512,
        memoryLimitMiB: 1024,
        desiredCount: 2,
      },
    ],
  }),
);

Fargate Spot (Cost Savings)

app.addCompute(
  ComputeFactory.build("BatchProcessor", {
    type: "ecs",
    services: [
      {
        name: "worker",
        capacityProvider: "FARGATE_SPOT",
        cpu: 256,
        memoryLimitMiB: 512,
        // Up to 70% cost savings
      },
    ],
  }),
);

EC2-backed ECS

app.addCompute(
  ComputeFactory.build("DevService", {
    type: "ecs",
    services: [
      {
        name: "dev",
        capacityProvider: "EC2",
        // EC2 services size the container via ec2Config; the service-level
        // cpu/memoryLimitMiB fields are Fargate-only.
        ec2Config: {
          instanceType: "t4g.micro",
          memoryLimitMiB: 512,
        },
      },
    ],
  }),
);

Lambda Functions

Deploy serverless functions with code deployment:

app.addCompute(
  ComputeFactory.build("MyFunction", {
    type: "lambda",
    deployment: "code", // Required discriminator
    handler: "index.handler",
    memorySize: 512,
    timeout: 30,
  }),
);

With container images:

import { Repository } from "aws-cdk-lib/aws-ecr";

// Reference an existing ECR repository
const ecrRepo = Repository.fromRepositoryName(scope, "FunctionRepo", "my-repo");

app.addCompute(
  ComputeFactory.build("ContainerFunction", {
    type: "lambda",
    deployment: "container", // Required discriminator
    ecrRepository: ecrRepo, // Required for container deployment
    memorySize: 1024,
  }),
);

Container-based Lambdas require an ECR repository. The ecrRepository parameter is required when deployment: "container". When using Fjall’s App scaffolding, ECR repositories are created automatically.

EC2 Instances

Deploy traditional virtual machines:

app.addCompute(
  ComputeFactory.build("MyInstance", {
    type: "ec2",
    instanceType: "t4g.micro",
    ssh: {},
    minCapacity: 1,
    maxCapacity: 3,
  }),
);

Configuration Parameters

Common Parameters

Parameter	Type	Description	Default
`type`	`"ecs" \| "lambda" \| "ec2"`	Compute type	`"ecs"`
`vpc`	`IVpc`	VPC to deploy into	App default VPC

Connection Syntax

Connect compute resources to databases, storage, and queues:

// Simple connection (default access)
const api = app.addCompute(
  ComputeFactory.build("API", {
    type: "ecs",
    services: [
      {
        name: "api",
        capacityProvider: "FARGATE",
        containers: [
          {
            environment: {
              DATABASE_HOST: database.getHostEndpoint(),
            },
          },
        ],
      },
    ],
  }),
);

ECS Parameters

Parameter	Type	Description	Default
`services`	`array`	Service configurations (see below)	Required

Service Configuration

Each service in the services array:

Parameter	Type	Description	Default
`name`	`string`	Service name	Required
`capacityProvider`	`"FARGATE" \| "FARGATE_SPOT" \| "EC2"`	Compute capacity	Required
`cpu`	`number`	CPU units (256, 512, 1024, etc.). Fargate only	`256`
`memoryLimitMiB`	`number`	Memory in MiB. Fargate only — EC2 uses `ec2Config.memoryLimitMiB`	`512`
`desiredCount`	`number`	Number of tasks	`1`
`containers`	`array`	Container definitions (see below)	Required
`routing`	`object`	ALB routing configuration	-
`scaling`	`object`	Auto-scaling configuration	-
`dockerfilePath`	`string`	Path to Dockerfile	`"Dockerfile"`
`dockerTarget`	`string`	Docker build target stage	-
`ssmSecretsPath`	`string`	SSM Parameter Store path prefix	-
`taskRoleInlinePolicies`	`object`	Custom IAM policies	-

Container Configuration

Each container in the containers array:

Parameter	Type	Description	Default
`name`	`string`	Container name	Service name
`port`	`number`	Container port	`80`
`image`	`string`	Container image (if not building)	-
`environment`	`object`	Environment variables	`{}`
`secretsImport`	`object`	Secrets from Secrets Manager	`{}`
`command`	`string[]`	Container command	-
`healthCheck`	`object`	Health check configuration	-

Routing Configuration

Parameter	Type	Description	Default
`path`	`string`	URL path pattern	`"/*"`
`host`	`string`	Host header match	-
`priority`	`number`	Rule priority	Auto
`healthCheckPath`	`string`	Health check endpoint	`"/"`

Scaling Configuration

Parameter	Type	Description	Default
`minCapacity`	`number`	Minimum tasks	`1`
`maxCapacity`	`number`	Maximum tasks	`1`
`scalingType`	`ScalingType`	Scaling metric (`ScalingType.CPU` or `ScalingType.MEMORY`)	`ScalingType.CPU`

scalingType takes the ScalingType enum, not a string. Import it from @fjall/components-infrastructure:

import { ScalingType } from "@fjall/components-infrastructure";

scaling: {
  minCapacity: 2,
  maxCapacity: 10,
  scalingType: ScalingType.CPU,
}

ECS Cluster Configuration

Configure the ECS cluster at the root level of the ComputeFactory:

Parameter	Type	Description	Default
`ecrRepository`	`IRepository`	ECR repository for container images	App default registry
`cluster`	`object`	Cluster-level configuration	-
`cluster.loadBalancer`	`"public" \| "internal" \| false`	Load balancer type	`"public"`
`cluster.directAccess`	`boolean`	Enable direct container access (no ALB)	`false`
`cluster.domain`	`string`	Custom domain for the cluster ALB	-
`cluster.domainConfig`	`object`	Domain configuration options	-
`cluster.domainConfig.certificateArn`	`string`	ACM certificate ARN	-
`cluster.domainConfig.hostedZoneId`	`string`	Route 53 hosted zone ID	-
`cluster.domainConfig.hostedZoneName`	`string`	Route 53 hosted zone name	-

Load Balancer Options

// Public load balancer (default) - internet-facing
app.addCompute(
  ComputeFactory.build("PublicAPI", {
    type: "ecs",
    cluster: {
      loadBalancer: "public",
    },
    services: [
      {
        name: "api",
        capacityProvider: "FARGATE",
        containers: [{ port: 3000 }],
      },
    ],
  }),
);

// Internal load balancer - VPC only
app.addCompute(
  ComputeFactory.build("InternalAPI", {
    type: "ecs",
    cluster: {
      loadBalancer: "internal",
    },
    services: [
      {
        name: "api",
        capacityProvider: "FARGATE",
        containers: [{ port: 3000 }],
      },
    ],
  }),
);

// No load balancer - direct container access
app.addCompute(
  ComputeFactory.build("Worker", {
    type: "ecs",
    cluster: {
      loadBalancer: false,
      directAccess: true,
    },
    services: [
      {
        name: "worker",
        capacityProvider: "FARGATE",
        containers: [{ port: 3000 }],
      },
    ],
  }),
);

Custom Domain Configuration

app.addCompute(
  ComputeFactory.build("WebApp", {
    type: "ecs",
    cluster: {
      loadBalancer: "public",
      domain: "api.example.com",
      domainConfig: {
        certificateArn: "arn:aws:acm:us-east-1:123456789:certificate/abc-123",
        hostedZoneId: "Z1234567890ABC",
        hostedZoneName: "example.com",
      },
    },
    services: [
      {
        name: "web",
        capacityProvider: "FARGATE",
        containers: [{ port: 3000 }],
      },
    ],
  }),
);

EC2 Capacity Provider Configuration

When using capacityProvider: "EC2", additional EC2-specific options are available:

Parameter	Type	Description	Default
`services[].ec2Config`	`object`	EC2-specific configuration	-
`services[].ec2Config.instanceType`	`string`	EC2 instance type	`"t4g.small"`
`services[].ec2Config.memoryLimitMiB`	`number`	Container hard memory limit — the only memory knob for EC2	`1024`
`services[].ec2Config.minCapacity`	`number`	Minimum EC2 instances	`2`
`services[].ec2Config.maxCapacity`	`number`	Maximum EC2 instances	`3`
`services[].ec2Config.desiredCapacity`	`number`	Initial instance count	-
`services[].ec2Config.amiHardwareType`	`"ARM" \| "STANDARD"`	AMI hardware type	`"ARM"`

The service-level cpu and memoryLimitMiB fields are Fargate only. On an EC2 service, size the container with ec2Config.memoryLimitMiB instead — from 4.2.0, setting either on EC2 capacity is rejected at synth.

Upgrading to 4.2.0 or later

Before 4.2.0 a service-level cpu or memoryLimitMiB on an EC2 service was silently ignored. A service whose config reads memoryLimitMiB: 2048 has in fact been running on ec2Config.memoryLimitMiB — or, where that was unset, on the 1024 MiB default. 4.2.0 rejects the ambiguous config at synth instead, with an error naming the field and the service. A service-level memoryLimitMiB that already matches ec2Config.memoryLimitMiB is accepted, so a redundant but consistent config needs no change. Check what the container is actually running before you move a value across. Copying memoryLimitMiB: 2048 into an ec2Config that had no memoryLimitMiB doubles the real memory limit at the next deploy — that may be what you wanted, but it is a change to a running workload, not a no-op config tidy. Deleting the ignored field instead leaves the deployed size exactly as it is. Two EC2 services in the same cluster share one Auto Scaling group when their ec2Config agrees on instanceType, amiHardwareType, warmPool, persistentDataVolume and availabilityZones. Those five fields are the sharing key. Every other ec2Config field — minCapacity, maxCapacity, desiredCapacity, instanceMonitoring, associatePublicIpAddress, machineImage, userData, blockDevices and tags — is read only when the group is first created. Before 5.0.0 the second service’s values for those fields were silently discarded, so it ran on whichever sizing the first service happened to declare. From 5.0.0 a mismatch is rejected at synth, naming both services and every field that differs. As with the memory guard, this is a narrowing: a config that synthesised on 4.x can fail on 5.0.0.

// Rejected from 5.0.0 — same sharing key, different minCapacity.
// Before 5.0.0 "reports" silently ran on minCapacity: 2.
{ name: "api",     ec2Config: { instanceType: "t4g.medium", minCapacity: 2 } },
{ name: "reports", ec2Config: { instanceType: "t4g.medium", minCapacity: 5 } }

There are two cures, and they mean different things:

Equalise the values if the services were always meant to share capacity. The group already runs on the first service’s numbers, so copying those onto the second is the no-op — copying the second service’s numbers onto the first resizes a running group.
Diverge one of the five keyed fields (a different instanceType, say) if the services were meant to scale independently. That gives each its own group, which is a new instance and a real cost change.

machineImage, userData and blockDevices are compared on presence only — set-versus-unset — because CDK gives them no cheap structural identity. Two services that each supply their own equivalent userData are accepted.

Upgrading to 12.0.0 — the EC2 default instance type and the memory-fit guard

Two related changes land in 12.0.0:

The default ec2Config.instanceType is now t4g.small (previously t4g.micro). The old default could never place a task: a micro registers roughly 896 MiB with ECS, below the 1024 MiB default container limit. A service that omitted instanceType gets its instances replaced on the next deploy — since that shape could never start a task before, no working workload is affected. Pin instanceType explicitly to opt out.
The synth-time memory-fit guard now applies to defaulted instance types too. If the sum of container hard memory limits reaches the instance type’s nominal memory, synth fails — whether the type was set explicitly or defaulted. On 11.x the defaulted shape only warned.

Explicit t4g.micro remains fully supported (it is what the free-tier Tinkerer preset pins, with memoryLimitMiB: 400): keep the container limits under roughly 896 MiB total and the guard stays quiet.

app.addCompute(
  ComputeFactory.build("EC2Service", {
    type: "ecs",
    services: [
      {
        name: "app",
        capacityProvider: "EC2",
        ec2Config: {
          instanceType: "t4g.large",
          minCapacity: 2,
          maxCapacity: 10,
          // The container hard limit for an EC2 service. The service-level
          // cpu/memoryLimitMiB fields are Fargate-only and are rejected here.
          memoryLimitMiB: 1024,
        },
      },
    ],
  }),
);

Multi-Container Service Example

import { ScalingType } from "@fjall/components-infrastructure";

app.addCompute(
  ComputeFactory.build("WebApp", {
    type: "ecs",
    services: [
      {
        name: "web",
        capacityProvider: "FARGATE",
        cpu: 512,
        memoryLimitMiB: 1024,
        containers: [
          {
            name: "app",
            port: 3000,
            environment: { NODE_ENV: "production" },
          },
          {
            name: "nginx",
            image: "nginx:alpine",
            port: 80,
          },
        ],
        routing: {
          path: "/*",
          healthCheckPath: "/health",
        },
        scaling: {
          minCapacity: 2,
          maxCapacity: 10,
          scalingType: ScalingType.CPU,
        },
      },
    ],
  }),
);

Lambda Parameters

Parameter	Type	Description	Default
`deployment`	`"code" \| "container"`	Deployment type (required)	Required
`handler`	`string`	Function handler (code deployment)	`"index.handler"`
`architecture`	`Architecture`	CPU architecture (`Architecture.ARM_64` or `Architecture.X86_64`)	`Architecture.ARM_64`
`timeout`	`number`	Timeout in seconds	`3`
`memorySize`	`number`	Memory in MB	`128`
`ephemeralStorageSize`	`number`	Ephemeral storage in MB (512-10240)	`512`
`environment`	`object`	Environment variables	`{}`
`functionUrl`	`object \| false`	Function URL configuration	-
`functionUrl.authType`	`FunctionUrlAuthType`	Auth type (NONE, AWS_IAM)	-
`functionUrl.cors`	`object`	CORS configuration	-
`ssmSecretsPath`	`string`	SSM Parameter Store path prefix for secrets	-
`inlinePolicy`	`PolicyStatement[]`	Custom IAM policy statements	-
`description`	`string`	Function description	-

architecture takes the Architecture enum from aws-cdk-lib/aws-lambda, not a string. Use Architecture.ARM_64 or Architecture.X86_64.

EC2 Parameters

Parameter	Type	Description	Default
`instanceType`	`string`	EC2 instance type	`"t4g.micro"`
`ssh`	`SshConfig \| false`	SSH access configuration	`false`
`userData`	`UserData`	Instance startup script	-
`machineImage`	`IMachineImage`	AMI to use	Latest Amazon Linux
`minCapacity`	`number`	Min instances in ASG	`1`
`maxCapacity`	`number`	Max instances in ASG	`1`

Database Connections

Connect compute resources to databases:

const database = app.addDatabase(
  DatabaseFactory.build("MyDatabase", {
    type: "Aurora",
    databaseName: "mydb",
  }),
);

app.addCompute(
  ComputeFactory.build("MyAPI", {
    type: "ecs",
    services: [
      {
        name: "api",
        capacityProvider: "FARGATE",
        containers: [
          {
            environment: {
              DATABASE_HOST: database.getHostEndpoint(),
              DATABASE_NAME: database.getDatabaseName(),
            },
            secretsImport: {
              DATABASE_PASSWORD: database
                .getCredentials()
                .getImport("password"),
            },
          },
        ],
      },
    ],
  }),
);

Lambda Function URLs

Make Lambda functions publicly accessible:

import { FunctionUrlAuthType } from "aws-cdk-lib/aws-lambda";
import { Duration } from "aws-cdk-lib";

app.addCompute(
  ComputeFactory.build("PublicAPI", {
    type: "lambda",
    deployment: "code",
    handler: "index.handler",
    functionUrl: {
      authType: FunctionUrlAuthType.NONE,
      cors: {
        allowedOrigins: ["*"],
        allowedMethods: ["GET", "POST"],
        allowedHeaders: ["Content-Type"],
        maxAge: Duration.hours(24),
      },
    },
  }),
);

Auto-Scaling

ECS services support auto-scaling:

app.addCompute(
  ComputeFactory.build("ScalableService", {
    type: "ecs",
    services: [
      {
        name: "api",
        capacityProvider: "FARGATE",
        desiredCount: 2,
        scaling: {
          minCapacity: 2,
          maxCapacity: 10,
        },
      },
    ],
  }),
);

Custom Domains

Configure custom domains for ECS services:

app.addCompute(
  ComputeFactory.build("WebApp", {
    type: "ecs",
    cluster: {
      domain: "app.example.com",
      domainConfig: {
        certificateArn: "arn:aws:acm:us-east-1:123456789:certificate/abc-123",
      },
    },
    services: [
      {
        name: "web",
        capacityProvider: "FARGATE",
        containers: [{ port: 3000 }],
      },
    ],
  }),
);

Cost Optimisation

Development Environments

Use Fargate Spot for cost savings:

// Fargate Spot for dev/test
app.addCompute(
  ComputeFactory.build("DevApp", {
    type: "ecs",
    services: [
      {
        name: "dev",
        capacityProvider: "FARGATE_SPOT",
        cpu: 256,
        memoryLimitMiB: 512,
      },
    ],
  }),
);

// Lambda for batch jobs
app.addCompute(
  ComputeFactory.build("BatchJob", {
    type: "lambda",
    deployment: "code",
    handler: "batch.handler",
    timeout: 900,
    memorySize: 1024,
  }),
);

Production Environments

Right-size resources:

app.addCompute(
  ComputeFactory.build("ProdAPI", {
    type: "ecs",
    services: [
      {
        name: "api",
        capacityProvider: "FARGATE",
        cpu: 512,
        memoryLimitMiB: 1024,
        desiredCount: 2,
        scaling: {
          minCapacity: 2,
          maxCapacity: 10,
        },
      },
    ],
  }),
);

Next Steps

Storage Factory

Create S3 buckets and storage resources.

Database Factory

Provision Aurora, RDS, DynamoDB, and ClickHouse databases.

Standard Pattern

Compose full applications from these factories.

ECS Cluster Resources

Configure ECS clusters for advanced workloads.

​Overview

​Basic Usage

​Compute Types

​ECS (Elastic Container Service)

​Fargate (Recommended)

​Fargate Spot (Cost Savings)

​EC2-backed ECS

​Lambda Functions

​EC2 Instances

​Configuration Parameters

​Common Parameters

​Connection Syntax

​ECS Parameters

​Service Configuration

​Container Configuration

​Routing Configuration

​Scaling Configuration

​ECS Cluster Configuration

​Load Balancer Options

​Custom Domain Configuration

​EC2 Capacity Provider Configuration

​Upgrading to 4.2.0 or later

​Upgrading to 5.0.0 — services that share an Auto Scaling group

​Upgrading to 12.0.0 — the EC2 default instance type and the memory-fit guard

​Multi-Container Service Example

​Lambda Parameters

​EC2 Parameters

​Database Connections

​Lambda Function URLs

​Auto-Scaling

​Custom Domains

​Cost Optimisation

​Development Environments

​Production Environments

​Next Steps

Storage Factory

Database Factory

Standard Pattern

ECS Cluster Resources

Overview

Basic Usage

Compute Types

ECS (Elastic Container Service)

Fargate (Recommended)

Fargate Spot (Cost Savings)

EC2-backed ECS

Lambda Functions

EC2 Instances

Configuration Parameters

Common Parameters

Connection Syntax

ECS Parameters

Service Configuration

Container Configuration

Routing Configuration

Scaling Configuration

ECS Cluster Configuration

Load Balancer Options

Custom Domain Configuration

EC2 Capacity Provider Configuration

Upgrading to 4.2.0 or later

Upgrading to 5.0.0 — services that share an Auto Scaling group

Upgrading to 12.0.0 — the EC2 default instance type and the memory-fit guard

Multi-Container Service Example

Lambda Parameters

EC2 Parameters

Database Connections

Lambda Function URLs

Auto-Scaling

Custom Domains

Cost Optimisation

Development Environments

Production Environments

Next Steps