Fjall Docs — deploy AWS infrastructure into your own account

Prerequisites

Complete these first:

Install the Fjall CLI
Sign in to Fjall with fjall login
Connect an AWS account with fjall connect
Deploy your organisation, optional, for multi-account setups

fjall create app authenticates before it scaffolds anything. The only exception is --offline, which writes files without registering the application.

Overview

A Fjall application is an infrastructure stack with compute, storage, and networking resources. Pick a tier preset or build a custom stack.

fjall create app

That opens the interactive wizard. To script the same thing, use non-interactive mode.

Application tiers

The first prompt, “Choose your starting point?”, lists six tiers in this order with Standard pre-highlighted. Resilient requires a Pro plan and Enterprise requires an Enterprise plan.

Tier	Compute	Database	Networking	Best for
Standard	Fargate, 512 CPU / 1024 MB, 2 to 5	RDS Instance `t4g.large`	3 AZ, 1 NAT Gateway, ECR endpoint	General production workloads
Lightweight	Fargate Spot, 256 CPU / 512 MB	RDS Instance `t4g.small`	2 AZ, 1 NAT Gateway	Low-traffic applications
Resilient	Fargate, 1024 CPU / 2048 MB, 4 to 20	Aurora, 2 readers, CMK, proxy	3 AZ, 3 NAT Gateways, 2 endpoints	High-availability workloads
Enterprise	Fargate, 2048 CPU / 4096 MB, 6 to 100	Aurora, 2 readers, CMK, proxy	3 AZ, 3 NAT Gateways, 4 endpoints	Regulated, compliance-sensitive workloads
Tinkerer	ECS on EC2 `t4g.micro`, 1 task	RDS Instance `t4g.micro`	2 AZ, no NAT Gateway	Learning and experimentation, free-tier
Custom	Added after creation	Added after creation	Preset chosen in the wizard	Specific requirements

Standard, Lightweight and Tinkerer default to an RDS Instance. Resilient and Enterprise default to Aurora. Resilient keeps 30-day backup retention and 90-day flow logs. Enterprise keeps 35-day retention, ships flow logs to S3 for 365 days, and adds a read replica to the Instance variant.

The tier picker is a fixed list. It never filters on database type, and the database question comes later in the wizard.

Interactive flow

After the tier, the wizard prompts for the rest. A tiered application asks:

Name your application? (for example, api)
Use suggested container ‘<dir>’? (Y/n) only when a monorepo container directory is inferred and --container was not passed. Answering no asks Container directory (leave empty for repo-root scaffold):
Include database?
Restore database from an existing RDS snapshot? only when a database is included. Answering yes asks for Snapshot identifier (ARN or name): then Master username from the snapshot (immutable, must match original):
How many services? (default 1, maximum 10, and Tinkerer accepts 1 only), then per service: Name service N of M?, What type of service is “X”? (asked only when the count is above 1), Provide Dockerfile for “X”?, Dockerfile path for “X”?, Container port for “X”? (skipped for workers and when an EXPOSE port is read from the Dockerfile), Does “X” need database connection? (asked only when the application includes a database)
Which frontend should be the main website (catch-all)? only when two or more frontend services exist
The review list, then Create application with these settings?
Select a deployment target: shown only when your organisation config derives more than one target. A single target is selected automatically, and a run with no derivable target skips the prompt

A Custom application skips steps 3 to 6 and asks Network configuration? instead, offering Standard, Lightweight, Resilient, Tinkerer, and No network.

fjall create app

? Choose your starting point?
  > Standard    Production-ready · Multi-AZ, Fargate ECS, RDS
    Lightweight Streamlined · Single-AZ, Instance-backed ECS, RDS
    Resilient   High-availability · Multi-AZ, Encrypted, Fargate ECS, Aurora
    Enterprise  Maximum capability · All features enabled, Aurora
    Tinkerer    Free experimental · Single-AZ, Free tier ECS, RDS
    Custom      Blank canvas · Build your way

? Name your application? api
? Include database? Yes
? Restore database from an existing RDS snapshot? No
? How many services? 1
? Name service 1 of 1? api
? Provide Dockerfile for "api"? Yes
? Dockerfile path for "api"? ./Dockerfile
? Container port for "api"? 3000
? Does "api" need database connection? Yes
? Create application with these settings? Yes

The wizard then runs the creation steps and prints a persistent summary after it exits:

Creating standard application: api

✓ Creating application structure
✓ Installing dependencies

Next Steps:
Review your infrastructure: fjall/api/infrastructure.ts
Deploy your changes: fjall deploy api
Learn more: https://docs.fjall.io/deployment/deploy-application

A third step, ✓ Setting up git repository, appears when you pass --git or --github.

What gets created

Your application structure:

fjall/
├── fjall-config.json      # Project marker and organisation binding
└── api/
    ├── infrastructure.ts  # CDK infrastructure code
    ├── Dockerfile         # Scaffolded for container apps, never overwritten
    ├── package.json       # Dependencies and scripts
    ├── cdk.json           # CDK configuration
    ├── cdk.context.json   # CDK context values
    └── tsconfig.json      # TypeScript configuration

fjall-config.json is committed and records the project’s organisation binding plus any domains. The active deployment target lives in a gitignored sibling, .fjall/local.json, so a teammate’s choice never re-aims your deploy. The Dockerfile is written only for applications with ECS compute, and only when you have not supplied your own with --dockerfile. Static-site and pattern applications get none.

Infrastructure code

The generated infrastructure.ts for a Standard application with a database:

#!/usr/bin/env node

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

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

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

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

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

Non-interactive mode

Pass --non-interactive with the options below to skip the wizard. Options on their own do not skip it: on a terminal they pre-fill the wizard and it still prompts, which is how a CI job hangs.

fjall create app \
  --non-interactive \
  -n api \
  -t standard \
  --database

-n, --name is required. --register-only and a non-TTY stdout also force the non-interactive path.

Application options

Option	Description	Example
`-n, --name`	Application name, required. 2 to 50 characters, lowercase-first kebab-case, no trailing or double hyphen	`-n api`
`-t, --type`	Application tier: `tinkerer`, `lightweight`, `standard`, `resilient`, `enterprise`, `custom`	`-t standard`
`--database`	Include a database	`--database`
`--dockerfile [path]`	Path to your own Dockerfile. Supplying one skips the scaffolded Dockerfile	`--dockerfile ./app/Dockerfile`
`--container-port`	Container port	`--container-port 8080`
`--services`	Service configuration as JSON	`--services '[{"name":"api"}]'`
`--owner`	Owner identifier, written to the cost-allocation tag	`--owner engineering`
`--network`	Network preset: `none`, `tinkerer`, `lightweight`, `standard`, `resilient`, `enterprise`	`--network standard`
`--container`	Monorepo container directory between the repo root and `fjall/`	`--container services`
`--into`	Scaffold into an existing repo at this path instead of `./fjall/<name>`	`--into ./apps/api`
`--target`	Deployment target for this command, persisted to `.fjall/local.json`	`--target production-use1`
`--snapshot-identifier`	RDS snapshot ID to restore from	`--snapshot-identifier my-snapshot`
`--snapshot-username`	Snapshot master username	`--snapshot-username admin`
`--template`	Preset option bundle: `api`, `dockerfile`, or `payload`	`--template api`
`--git`	Initialise a local git repository	`--git`
`--github`	Create a GitHub repository	`--github`
`--github-org`	GitHub organisation for the new repository	`--github-org acme`
`--repo-visibility`	Repository visibility: `private` or `public`	`--repo-visibility private`
`--dry-run`	Preview the scaffold. Writes no files, calls no API, installs nothing	`--dry-run`
`--offline`	Scaffold with no network at all. Files are written but the application is not registered	`--offline`
`--register-only`	Register an existing application tree without scaffolding. Run from the application’s package root	`--register-only`
`--file-override`	Replace a planned scaffold file with base64 content, repeatable	`--file-override src/x.ts=<base64>`

Three refusals to plan around:

--offline conflicts with --github, which needs a GitHub identity, and with --target, which is checked against your organisation.
--offline is refused for the paid tiers. Create offline with tinkerer, lightweight, standard, or custom.
--register-only conflicts with --dry-run, --offline, --git, --github, --services, --dockerfile, --container-port, --file-override, --owner, --network, --snapshot-identifier/--snapshot-username, and the static-site flags (--source, --build-command, --output-dir, --routing, --forms-to, --cors-origin).

Pattern options

Patterns are a separate scaffold path, driven by --pattern and valid only in non-interactive mode. The interactive wizard drops pattern flags and lands in the six-tier picker, so reach patterns interactively through bare fjall create, then Patterns.

Option	Description	Example
`--pattern`	Application pattern: `payload` or `staticsite`	`--pattern payload`
`--tier`	Pattern infrastructure tier: `lightweight`, `standard`, `resilient`, `custom`. `--pattern-tier` is an alias	`--tier standard`
`--pattern-domain`	Custom domain for the pattern	`--pattern-domain example.com`
`--source`	Static-site source directory. The build runs here	`--source ./site`
`--build-command`	Static-site build command	`--build-command "npm run build"`
`--output-dir`	Static-site build output directory, relative to `--source`	`--output-dir out`
`--routing`	Static-site routing mode: `multipage`, `directory`, or `spa`	`--routing spa`
`--forms-to`	Static-site contact-form recipient. Requires `--pattern-domain`	`--forms-to hello@example.com`
`--cors-origin`	Static-site forms CORS allow-origin, defaults to the site domain	`--cors-origin https://example.com`

--tier is narrower than -t, --type: tinkerer and enterprise are not pattern tiers.

The nextjs pattern is not deployable. It is hidden from the picker, and --pattern nextjs is refused at create time. Use --pattern payload for a Next.js application, or --pattern staticsite for a pre-built static site.

Create an application on its own or as part of an organisation. For multi-account setups, deploy the organisation first. In agent mode the same flow is spelled fjall apps create.

Next Steps

Deploy Application

Deploy your application to AWS.

Add Resources

Extend with databases, storage, and more.

Connect AWS

Connect the AWS account your application deploys into.

Deploy Organisation

Set up multi-account management with Fjall.

Install & Setup

Application Deploy

Deployment Errors

Organisation Setup

Organisation Deploy

Create Application

Prerequisites

Overview

Application tiers

Interactive flow

What gets created

Infrastructure code

Non-interactive mode

Application options

Pattern options

Next Steps

Deploy Application

Add Resources

Connect AWS

Deploy Organisation

​Prerequisites

​Overview

​Application tiers

​Interactive flow

​What gets created

​Infrastructure code

​Non-interactive mode

​Application options

​Pattern options

​Next Steps

Deploy Application

Add Resources

Connect AWS

Deploy Organisation

Prerequisites

Overview

Application tiers

Interactive flow

What gets created

Infrastructure code

Non-interactive mode

Application options

Pattern options

Next Steps