Fjall Docs — deploy AWS infrastructure into your own account

Overview

Standard is the recommended starting point for production workloads. It runs on-demand Fargate tasks across 3 availability zones behind an Application Load Balancer, backed by a Multi-AZ RDS PostgreSQL instance, with CPU auto-scaling and CloudWatch alarms already wired. Everything below is scaffolded into fjall/myapp/infrastructure.ts, which you own and edit like any other TypeScript file.

Create a Standard application

fjall create app --name myapp --type standard

In a terminal the flags seed the prompts rather than skip them, so you still confirm the name, database and services. Add --non-interactive to run it straight through. Omit --type to pick Standard from the tier list, where it is the pre-highlighted option. You get:

Component	Standard tier configuration
ECS Fargate cluster	1 service, 2 tasks, scaling 2 to 5
Application Load Balancer	Public, across 3 AZs
RDS PostgreSQL Instance	`t4g.large`, Multi-AZ, encrypted
VPC	3 AZs, 1 NAT gateway, flow logs
VPC endpoints	S3 + DynamoDB gateway, ECR interface
CloudWatch	Log groups, metrics, alarm thresholds

Architecture

┌──────────────────┐
│    CloudFront    │  optional, add with `fjall add cdn`
└────────┬─────────┘
         │
┌────────┴─────────┐
│       ALB        │  public subnets, 3 AZs
└────────┬─────────┘
         │
┌────────┴─────────┐
│   ECS Fargate    │  private subnets
│   512 CPU        │  2 tasks, scales 2 to 5
│   1024 MiB       │  target-tracking on CPU at 50%
└────────┬─────────┘
         │
┌────────┴─────────┐
│   RDS Instance   │  private subnets
│   t4g.large      │  primary + Multi-AZ standby
└──────────────────┘

Generated infrastructure

This is what the Standard tier scaffolds into fjall/myapp/infrastructure.ts.

#!/usr/bin/env node

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

const appName = "myapp";
const app = App.getApp(appName, {
  network: {
    maxAzs: 3,
    natGateways: { count: 1 },
    vpcEndpoints: {
      interface: { ecr: true },
    },
  },
});

app.addTags({
  "fjall:costAllocation:owner": "engineering",
});

const myappDatabase = app.addDatabase(
  DatabaseFactory.build("myapp", {
    vpc: app.getVpc(),
    type: "Instance",
    databaseName: "myapp",
    instanceType: "t4g.large",
    ...(getConfig().environment === "production"
      ? { alertsTopic: "import:SharedAlarmTopicArn" }
      : {}),
  }),
);

app.addCompute(
  ComputeFactory.build("myapp", {
    type: "ecs",
    ecrRepository: app.getDefaultContainerRegistry(),
    services: [
      {
        name: "api",
        capacityProvider: "FARGATE",
        containers: [
          {
            port: 3000,
            environment: {
              ENVIRONMENT: getConfig().environment,
              DATABASE_HOST: myappDatabase.getHostEndpoint(),
              DATABASE_PORT: myappDatabase.getHostPort(),
              DATABASE_NAME: myappDatabase.getDatabaseName(),
              DATABASE_SSL: "true",
            },
            secretsImport: {
              DATABASE_USERNAME: myappDatabase
                .getCredentials()
                .getImport("username"),
              DATABASE_PASSWORD: myappDatabase
                .getCredentials()
                .getImport("password"),
            },
          },
        ],
        cpu: 512,
        memoryLimitMiB: 1024,
        desiredCount: 2,
        scaling: {
          minCapacity: 2,
          maxCapacity: 5,
        },
        connections: [myappDatabase],
      },
    ],
    ...(getConfig().environment === "production"
      ? { alertsTopic: "import:SharedAlarmTopicArn" }
      : {}),
  }),
);

getConfig().environment comes from the target account’s recorded stage, not from a flag. Deploying into an account stamped production wires the shared alarm topic and switches removal policies to retain.

Specifications

Compute (ECS Fargate)

Setting	Value
CPU	512 units (0.5 vCPU)
Memory	1024 MiB
Tasks	2 desired, minimum 2, maximum 5
Capacity	`FARGATE` (on-demand)
Auto-scaling	Target tracking on average CPU, 50% target
Cooldowns	60 seconds scale-in, 60 seconds scale-out
Health checks	ALB target-group checks against the primary container port

Database (RDS Instance)

Setting	Value
Engine	PostgreSQL 17.9
Instance class	`t4g.large`
Multi-AZ	Enabled by default
Storage	100 GiB gp3, autoscaling to 500 GiB
Encryption at rest	On, AWS-managed KMS key
Automated backups	14-day retention
AWS Backup vault	Standard plan: daily at 02:00 UTC, 90 days
Deletion protection	On by default
Maintenance window	`Sat:12:30-Sat:20:30` UTC

Automated backups and AWS Backup are different protections. Standard gets 14 days of RDS automated backups and point-in-time recovery, plus a daily vault snapshot kept for 90 days. What Standard does not get is a copy anywhere else: continuous (second-level) recovery — for the resource types AWS supports it on — and a cross-region copy start at the Resilient tier, and a cross-account copy at Enterprise. S3 buckets are not enrolled at Standard either — AWS Backup requires bucket versioning, which this tier leaves off; set versioned: true on a bucket to enrol it, or move the app to Resilient. Enrolment at every tier also depends on a setting Fjall does not own: AWS Backup’s per-Region service opt-in must admit the resource type, or a tagged resource is in no plan at all while the plan still reports healthy. Check AWS Backup console → Settings → Service opt-in in each account and Region you deploy into.

Networking

Setting	Value
VPC	3 AZs, public and private subnets
NAT gateways	1
Load balancer	Application Load Balancer in the public subnets
Gateway endpoints	S3, DynamoDB
Interface endpoints	ECR (`ecr.api` and `ecr.dkr`), one ENI per AZ
Flow logs	On, to CloudWatch Logs
Security groups	Generated per resource, least privilege
TLS	ACM certificate attached when you add a custom domain

The ECR interface endpoints let tasks pull images without traversing the NAT gateway. They cost roughly $0.01 per AZ per hour each, so 2 endpoints across 3 AZs is the second-largest fixed line item after the database.

Customisation

Change scaling

app.addCompute(
  ComputeFactory.build("myapp", {
    type: "ecs",
    ecrRepository: app.getDefaultContainerRegistry(),
    services: [
      {
        name: "api",
        capacityProvider: "FARGATE",
        cpu: 1024,
        memoryLimitMiB: 2048,
        desiredCount: 4,
        scaling: {
          minCapacity: 4,
          maxCapacity: 10,
        },
        containers: [{ port: 3000 }],
        connections: [myappDatabase],
      },
    ],
  }),
);

Omitting scaling keeps auto-scaling on with minCapacity tracking desiredCount and maxCapacity defaulting to Math.max(desiredCount + 1, 3). Setting scaling: false disables auto-scaling entirely.

Resize the database

const myappDatabase = app.addDatabase(
  DatabaseFactory.build("myapp", {
    vpc: app.getVpc(),
    type: "Instance",
    databaseName: "myapp",
    instanceType: "t4g.xlarge",
    allocatedStorage: 200,
  }),
);

Turn Multi-AZ off

Multi-AZ is on unless you set it to false. Single-AZ roughly halves the database bill and gives up automatic failover, so it suits development accounts rather than production.

const myappDatabase = app.addDatabase(
  DatabaseFactory.build("myapp", {
    vpc: app.getVpc(),
    type: "Instance",
    databaseName: "myapp",
    instanceType: "t4g.large",
    multiAz: false,
  }),
);

Or edit it from the CLI, then deploy:

fjall modify database -a myapp -n myapp --multiAz false
fjall deploy myapp

Change the database through infrastructure.ts or fjall modify, never with aws rds modify-db-instance. An out-of-band change creates CloudFormation drift that the next fjall deploy reverts. Run fjall drift detect if you suspect a resource has been changed outside Fjall.

Add a background worker

A worker belongs in the same cluster as the API, so add a second entry to services. A worker declares no port, so it gets no ALB target group.

services: [
  {
    name: "api",
    capacityProvider: "FARGATE",
    cpu: 512,
    memoryLimitMiB: 1024,
    desiredCount: 2,
    containers: [{ port: 3000 }],
    connections: [myappDatabase],
  },
  {
    name: "worker",
    serviceType: "worker",
    capacityProvider: "FARGATE",
    cpu: 256,
    memoryLimitMiB: 512,
    desiredCount: 1,
    containers: [{}],
    connections: [myappDatabase],
  },
],

To scaffold a separate cluster instead, fjall add compute requires --type and --needsConnection on a first add:

fjall add compute -a myapp -n Worker --type ecs --needsConnection true --connectedDatabase '["myapp"]'

See Add Resources for the full property list.

Monitoring

Standard writes container logs to CloudWatch Logs and publishes ECS, RDS and ALB metrics. Alarms are declared on the factory, not with raw CDK.

Alarm thresholds

Per-service alarms materialise once an alertsTopic is set on the compute. The generated file wires the shared organisation topic automatically in production accounts.

services: [
  {
    name: "api",
    capacityProvider: "FARGATE",
    alarms: {
      cpuThreshold: 80,
      memoryThreshold: 80,
      http5xxThreshold: 5,
      p99ResponseTimeThresholdMs: 3000,
    },
    containers: [{ port: 3000 }],
  },
],

Threshold	Default	Period	Fires on	Notes
`cpuThreshold`	80%	5 min	2 of 3	`false` disables the CPU alarm
`memoryThreshold`	80%	5 min	2 of 3	`false` disables the memory alarm
`http5xxThreshold`	5%	5 min	2 of 2	ALB-attached services only
`p99ResponseTimeThresholdMs`	3000	5 min	3 of 3	ALB-attached services only, threshold in milliseconds
`runningTasksMinimum`	1	1 min	2 of 2	Needs `containerInsights: true`; `0` disables the alarm

Every alarm treats missing data as not breaching and notifies on both ALARM and OK transitions. Set alarms: false on a service to opt it out.

Cost

Indicative us-east-1 on-demand list prices for the tier defaults, excluding data transfer and request-based charges.

Resource	Specification	Monthly
RDS Instance	`t4g.large` PostgreSQL, Multi-AZ	~$188
RDS storage	100 GiB gp3, Multi-AZ	~$23
ECR interface endpoints	2 endpoints x 3 AZs	~$44
ECS Fargate	0.5 vCPU, 1 GB x 2 tasks	~$36
NAT gateway	1 gateway	~$33
Load balancer	1 ALB, base hours	~$16
Total		~$340

The database dominates. Dropping to single-AZ saves roughly $105 a month, and the Lightweight tier trades HA for a much smaller bill. Run fjall costs --app myapp for your actual spend once the application is deployed.

When to use

Choose Standard for:

Production web applications and APIs
Business applications and SaaS products
Mobile app backends
Anything that needs automatic database failover from day one

Choose something else if:

Situation	Tier
Aurora, CMK encryption, enhanced monitoring	Resilient
Every capability enabled, multi-region ready	Enterprise
Cost-sensitive with low traffic	Lightweight
Experimenting or learning, free tier	Tinkerer
Blank canvas, resources added by hand	Custom (pick it in `fjall create app`)

Production checklist

Standard already ships Multi-AZ, encryption at rest, deletion protection and 14-day backups. What is left to you:

Attach a custom domain and TLS certificate
Set alarm thresholds that match your traffic, and confirm the alerts topic is receiving them
Add containerInsights: true if you want the running-tasks alarm
Load-test and confirm 2 to 5 tasks covers your peak
Review generated security groups against your own rules
Store application secrets with fjall secret, not in environment
Wire up CI/CD so deploys are reproducible
Run fjall drift detect on a schedule

Security

Control	Standard
Encryption at rest	RDS storage encrypted with the AWS-managed KMS key
Network isolation	Database and tasks in private subnets, no public IP
Secrets	Database credentials in Secrets Manager, injected at runtime
IAM	Per-service task roles, scoped to declared connections
Security groups	Generated from the `connections` array, least privilege

Customer-managed KMS keys, RDS Proxy with requireTLS, and advanced Database Insights start at Resilient.

Upgrade paths

To Resilient

Resilient swaps the RDS Instance for Aurora with a reader, adds CMK encryption on storage and Database Insights, adds RDS Proxy with TLS required, and enrols the application in an AWS Backup vault. Scaffold a new application at that tier and port your resources, or edit infrastructure.ts directly.

Add a CDN

--defaultOriginRef names the resource the distribution fronts, which is the compute resource in a Standard application.

fjall add cdn -a myapp -n MyappCdn --defaultOriginRef myapp

Add storage or messaging

fjall add storage -a myapp -n Uploads --preset upload
fjall add messaging -a myapp -n Jobs

Troubleshooting

Container fails to start

Read the service logs in CloudWatch Logs under the application’s log group.
Check the container port matches the port in infrastructure.ts (3000 by default).
Confirm the image built and pushed: fjall build myapp.
Check the task has enough memory. A task killed at 1024 MiB shows as OutOfMemoryError in the stopped-task reason.

Database connection failures

Confirm the service declares the database in connections. That array is what generates the security-group rule.
Check DATABASE_HOST, DATABASE_PORT and DATABASE_NAME in the task definition.
Confirm the credentials import resolved. secretsImport pulls from Secrets Manager at task start.
For interactive access, open a tunnel: fjall tunnel myapp.

Costs higher than expected

Run fjall costs --mode attribution --app myapp.
Check whether auto-scaling is sitting at maxCapacity. A 50% CPU target on a bursty service holds more tasks than you might expect.
Consider single-AZ for non-production accounts.
Drop vpcEndpoints.interface.ecr if image pulls are infrequent and NAT egress is cheaper for your volume.

Breaking out the pattern

Standard is a starting scaffold, not a lock-in. The generated file is ordinary factory calls, so you can add, replace or delete any of them.

Factory	Use it for
Compute Factory	ECS, Lambda and EC2 settings
Database Factory	RDS and Aurora parameters
Storage Factory	S3 buckets
Network Factory	Custom VPC and networking
CDN Factory	CloudFront distributions
Messaging Factory	SQS, SNS and EventBridge

Next Steps

Deploy Application

Ship your Standard application to AWS

Add Resources

Extend with storage, messaging, or a CDN

Resilient Pattern

Step up to Aurora, CMK encryption, and backup vaults

Enterprise Pattern

Every capability enabled, multi-region ready

Compute Factory

Tune ECS services, scaling, and alarms

Configure CI/CD

Automate deploys from your pipeline

Factory Patterns

Application Patterns

Architecture Patterns

Standard Pattern

Overview

Create a Standard application

Architecture

Generated infrastructure

Specifications

Compute (ECS Fargate)

Database (RDS Instance)

Networking

Customisation

Change scaling

Resize the database

Turn Multi-AZ off

Add a background worker

Monitoring

Alarm thresholds

Cost

When to use

Production checklist

Security

Upgrade paths

To Resilient

Add a CDN

Add storage or messaging

Troubleshooting

Container fails to start

Database connection failures

Costs higher than expected

Breaking out the pattern

Next Steps

Deploy Application

Add Resources

Resilient Pattern

Enterprise Pattern

Compute Factory

Configure CI/CD

​Overview

​Create a Standard application

​Architecture

​Generated infrastructure

​Specifications

​Compute (ECS Fargate)

​Database (RDS Instance)

​Networking

​Customisation

​Change scaling

​Resize the database

​Turn Multi-AZ off

​Add a background worker

​Monitoring

​Alarm thresholds

​Cost

​When to use

​Production checklist

​Security

​Upgrade paths

​To Resilient

​Add a CDN

​Add storage or messaging

​Troubleshooting

​Container fails to start

​Database connection failures

​Costs higher than expected

​Breaking out the pattern

​Next Steps

Deploy Application

Add Resources

Resilient Pattern

Enterprise Pattern

Compute Factory

Configure CI/CD

Overview

Create a Standard application

Architecture

Generated infrastructure

Specifications

Compute (ECS Fargate)

Database (RDS Instance)

Networking

Customisation

Change scaling

Resize the database

Turn Multi-AZ off

Add a background worker

Monitoring

Alarm thresholds

Cost

When to use

Production checklist

Security

Upgrade paths

To Resilient

Add a CDN

Add storage or messaging

Troubleshooting

Container fails to start

Database connection failures

Costs higher than expected

Breaking out the pattern

Next Steps