Fjall Docs — deploy AWS infrastructure into your own account

Overview

The Tinkerer tier targets experimentation and learning. It runs ECS on a single t4g.micro EC2 instance with direct port mapping, and pairs it with a t4g.micro RDS Instance. It drops the two largest fixed costs in a Fjall stack: the NAT gateway and the Application Load Balancer. The database sits in a public subnet because there is no NAT gateway to route its traffic.

The Tinkerer tier is for learning and throwaway projects. A publicly accessible database, a single instance with no load balancer, and no Multi-AZ make it unsuitable for anything you care about.

Create a Tinkerer application

fjall create app --name experiment --type tinkerer

Application names are lowercase letters, numbers, and hyphens, starting with a letter. Run fjall create app with no flags to pick the tier interactively. The picker lists Tinkerer as “Free experimental · Single-AZ, Free tier ECS, RDS”.

The Tinkerer tier caps you at one service. The interactive prompt reads “How many services? (tinkerer tier: 1 only)” and rejects anything higher.

What you get

Component	Configuration
Compute	ECS on EC2, one t4g.micro (ARM), 400 MiB container memory
Access	Direct port mapping on port 3000, no Application Load Balancer
Database	RDS Instance, t4g.micro, PostgreSQL, single-AZ, publicly accessible
Networking	VPC across 2 AZs, no NAT gateway, no flow logs
Backup	No backup plan (`backup: false`)

Architecture

VPC (2 AZs, no NAT gateway)
┌──────────────────────────────────────────────┐
│  Public subnet                               │
│  ┌────────────────────┐                      │
│  │  ECS on EC2        │  Direct port mapping │
│  │  t4g.micro (ARM)   │  :3000, no ALB       │
│  │  400 MiB container │                      │
│  └─────────┬──────────┘                      │
│            │                                 │
│  ┌─────────┴──────────┐                      │
│  │  RDS Instance      │  publiclyAccessible  │
│  │  t4g.micro         │  single-AZ           │
│  └────────────────────┘                      │
└──────────────────────────────────────────────┘

Generated infrastructure

fjall create app --name experiment --type tinkerer writes this to fjall/experiment/infrastructure.ts:

#!/usr/bin/env node

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

const appName = "experiment";
const app = App.getApp(appName, {
  network: {
    maxAzs: 2,
    natGateways: false,
    flowLogs: false,
  },
});

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

const experimentDatabase = app.addDatabase(
  DatabaseFactory.build("experiment", {
    vpc: app.getVpc(),
    type: "Instance",
    databaseName: "experiment",
    instanceType: "t4g.micro",
    multiAz: false,
    publiclyAccessible: true,
    proxy: false,
    readReplica: false,
    ...(getConfig().environment === "production"
      ? { alertsTopic: "import:SharedAlarmTopicArn" }
      : {}),
  }),
);

app.addCompute(
  ComputeFactory.build("experiment", {
    type: "ecs",
    ecrRepository: app.getDefaultContainerRegistry(),
    cluster: { directAccess: true },
    services: [
      {
        name: "api",
        capacityProvider: "EC2",
        ec2Config: {
          instanceType: "t4g.micro",
          amiHardwareType: "ARM",
          minCapacity: 1,
          maxCapacity: 1,
          memoryLimitMiB: 400,
        },
        containers: [
          {
            port: 3000,
            environment: {
              ENVIRONMENT: getConfig().environment,
              DATABASE_HOST: experimentDatabase.getHostEndpoint(),
              DATABASE_PORT: experimentDatabase.getHostPort(),
              DATABASE_NAME: experimentDatabase.getDatabaseName(),
              DATABASE_SSL: "true",
            },
            secretsImport: {
              DATABASE_USERNAME: experimentDatabase
                .getCredentials()
                .getImport("username"),
              DATABASE_PASSWORD: experimentDatabase
                .getCredentials()
                .getImport("password"),
            },
          },
        ],
        desiredCount: 1,
        scaling: {
          minCapacity: 1,
          maxCapacity: 1,
        },
        connections: [experimentDatabase],
      },
    ],
    ...(getConfig().environment === "production"
      ? { alertsTopic: "import:SharedAlarmTopicArn" }
      : {}),
  }),
);

Construct ids come from the application name, so both the database and the compute cluster are called experiment. Use those names with fjall modify and fjall remove.

Specifications

Compute (ECS on EC2)

Setting	Value
Instance type	t4g.micro (Graviton, ARM)
Container memory	400 MiB
Access	Direct port mapping, no Application Load Balancer
Scaling	Fixed at one instance and one task
Services	One

Container images build for linux/arm64 to match the Graviton instance.

Database (RDS Instance)

Setting	Value
Instance type	t4g.micro
Engine	PostgreSQL 17.9 (pinned by the construct)
Storage	100 GiB gp3 (CDK default, the tier sets no `allocatedStorage`)
Storage autoscaling	Up to 500 GiB
Backup retention	14 days (construct default)
Multi-AZ	Disabled by the Tinkerer preset. Set `multiAz: true` to enable
Public access	`publiclyAccessible: true`, placed in a public subnet
Deletion protection	On, with a snapshot taken on removal

Networking

Setting	Value
VPC	2 availability zones
NAT gateways	None
Flow logs	Disabled
Subnets	Public and private

Cost

The Tinkerer tier picks the smallest instance sizes and skips the NAT gateway and the load balancer, which is most of what a small stack costs. It is not a guarantee of a zero bill. Three scaffolded defaults sit outside the AWS free-tier allowances. Fix them before you deploy if a zero bill matters.

Item	Scaffolded default	Free-tier allowance	Fix
RDS storage	100 GiB gp3	20 GB	`allocatedStorage: 20`
Backup retention	14 days	20 GB of snapshots	`backupRetention: 1`
Instance hours	720/month at 24/7, per instance	750 hrs/month	Destroy when idle

Apply the first two in one command:

fjall modify database -a experiment -n experiment \
  --allocatedStorage 20 --backupRetention 1

Free-tier eligibility depends on your account age and on the instance family, and AWS changes both. Check the current allowances at aws.amazon.com/free and set a billing alarm at

1,

5, and $10 before you deploy.

Indicative us-east-1 on-demand rates once you fall outside the free tier:

t4g.micro EC2: around $0.0084/hour
db.t4g.micro RDS: around $0.016/hour
Data transfer out beyond 100 GB: $0.09/GB

Track spend

fjall costs --mode summary -a experiment
fjall costs --mode attribution -a experiment --days 30
fjall costs --mode forecast -a experiment --forecast-days 30

Customise the stack

Container environment variables

Add keys to the environment block inside the service’s containers entry. The scaffolded database keys stay as they are, since they resolve at synth time.

containers: [
  {
    port: 3000,
    environment: {
      ENVIRONMENT: getConfig().environment,
      DATABASE_HOST: experimentDatabase.getHostEndpoint(),
      DATABASE_PORT: experimentDatabase.getHostPort(),
      DATABASE_NAME: experimentDatabase.getDatabaseName(),
      DATABASE_SSL: "true",
      FEATURE_FLAGS: "experimental",
      LOG_LEVEL: "debug",
    },
    secretsImport: {
      DATABASE_USERNAME: experimentDatabase.getCredentials().getImport("username"),
      DATABASE_PASSWORD: experimentDatabase.getCredentials().getImport("password"),
    },
  },
],

Secrets belong in secretsImport or in Parameter Store via fjall secret, never in environment.

Add a Lambda function

Lambda’s always-free tier covers 1M requests and 400,000 GB-seconds per month, which suits sporadic work better than a second container.

fjall add compute -a experiment -n Worker \
  --type lambda --needsConnection false --memory 128 --timeout 30

--type and --needsConnection are both required on a first compute add. Resource names are alphanumeric and start with a letter.

Working within the limits

400 MiB of container memory

The task is capped at 400 MiB. A Node or Python process that fits locally can still be OOM-killed on the instance.

Build from a slim base image
Drop dependencies you do not import
Cap heap size explicitly, for example NODE_OPTIONS=--max-old-space-size=320
Read the ECS task logs after a restart to confirm whether the kill was OOM

Database connections

A t4g.micro instance allows few concurrent connections.

Pool connections rather than opening one per request
Close idle connections
Retry on connection failure with backoff

Local development

Run the same image locally against a local Postgres, using the variable names the scaffold injects.

services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_HOST=db
      - DATABASE_PORT=5432
      - DATABASE_NAME=experiment
      - DATABASE_USERNAME=postgres
      - DATABASE_PASSWORD=localpass
      - DATABASE_SSL=false
    depends_on:
      - db

  db:
    image: postgres:17-alpine
    environment:
      - POSTGRES_DB=experiment
      - POSTGRES_PASSWORD=localpass

Suitability

Good fit:

Learning AWS and Fjall
Personal projects and portfolio applications
Proof of concepts
Hackathon projects

Wrong fit:

Production workloads
Anything needing a load balancer or a custom domain on the service
Multi-AZ or failover requirements
Databases over a few gigabytes
CPU-intensive or memory-hungry workloads

Move beyond the Tinkerer tier

Tiers are chosen at scaffold time and are not switchable in place. Create a new application at the tier you want, then migrate data and cut traffic over.

# Fargate, single-AZ, still low cost
fjall create app --name production --type lightweight

# Multi-AZ, Fargate, production-ready
fjall create app --name production --type standard

Alternatively, keep the application and edit infrastructure.ts directly. The tier only seeds the first version of that file, so every factory call is yours to change:

Compute Factory for ECS and Lambda settings
Database Factory for RDS parameters
Storage Factory for S3 buckets
Network Factory for VPC and networking

Run fjall validate --deep after hand-editing to typecheck the file before you deploy.

Next Steps

Deploy your application

Ship the Tinkerer stack to AWS.

Add resources

Extend the application with databases, compute, storage, and more.

Move to Lightweight

Switch to Fargate when you outgrow the single instance.

Move to Standard

Run a production-ready, multi-AZ stack.

Factory Patterns

Application Patterns

Architecture Patterns

Tinkerer Pattern

Overview

Create a Tinkerer application

What you get

Architecture

Generated infrastructure

Specifications

Compute (ECS on EC2)

Database (RDS Instance)

Networking

Cost

Track spend

Customise the stack

Container environment variables

Add a Lambda function

Working within the limits

400 MiB of container memory

Database connections

Local development

Suitability

Move beyond the Tinkerer tier

Next Steps

Deploy your application

Add resources

Move to Lightweight

Move to Standard

​Overview

​Create a Tinkerer application

​What you get

​Architecture

​Generated infrastructure

​Specifications

​Compute (ECS on EC2)

​Database (RDS Instance)

​Networking

​Cost

​Track spend

​Customise the stack

​Container environment variables

​Add a Lambda function

​Working within the limits

​400 MiB of container memory

​Database connections

​Local development

​Suitability

​Move beyond the Tinkerer tier

​Next Steps

Deploy your application

Add resources

Move to Lightweight

Move to Standard

Overview

Create a Tinkerer application

What you get

Architecture

Generated infrastructure

Specifications

Compute (ECS on EC2)

Database (RDS Instance)

Networking

Cost

Track spend

Customise the stack

Container environment variables

Add a Lambda function

Working within the limits

400 MiB of container memory

Database connections

Local development

Suitability

Move beyond the Tinkerer tier

Next Steps