Fjall Docs — deploy AWS infrastructure into your own account

Overview

The Payload pattern deploys a Payload CMS application to AWS Lambda. Payload 3.x runs on Next.js, so Fjall builds it with OpenNext and fronts it with CloudFront. One pattern statement provisions the whole stack:

Serverless compute: three ARM64 Lambda functions (server, image, revalidation)
Managed PostgreSQL: RDS Instance by default, Aurora Serverless v2 on the Resilient tier
S3 storage: three buckets for build assets, ISR cache, and media uploads
CloudFront CDN: HTTPS, path-based routing, and edge caching
Automatic patching: the CLI rewrites your Payload project for Lambda at deploy time

Prerequisites

Requirement	Detail
Node.js	22.3 or later
Fjall CLI	Installed and logged in (`fjall login`)
AWS account	Connected with `fjall connect`
Payload project	Scaffolded with PostgreSQL as the database

Quick start

1. Scaffold a Payload project

Start with the official website template:

npx create-payload-app@latest my-payload-site --template website
cd my-payload-site

Choose PostgreSQL when prompted. Fjall provisions RDS PostgreSQL for this pattern and does not support MongoDB.

2. Create the Fjall application

fjall create app \
  --name my-payload-site \
  --pattern payload \
  --tier standard \
  --non-interactive

--pattern and --tier are honoured only on the non-interactive path. On a TTY, fjall create app opens the application wizard, which has no pattern step and silently drops both flags. Either pass --non-interactive as above, or run bare fjall create and choose Patterns from the menu.

This writes fjall/my-payload-site/infrastructure.ts plus the application’s config file. The scaffold directory is named after --name.

3. Deploy

fjall deploy my-payload-site

Fjall patches the project for Lambda, builds it with OpenNext, and provisions the infrastructure.

Choosing a pattern

The interactive picker offers two patterns:

Pattern	Value	Use it for
Payload CMS	`payload`	A CMS or any Next.js application that needs SSR
Static site	`staticsite`	A pre-built folder of files (docs)

A nextjs pattern exists in the registry but has no infrastructure construct, so it is not offered in the picker and --pattern nextjs is refused at create time. For a Next.js application that needs a server, use --pattern payload. For a static export, use --pattern staticsite.

Choosing a tier

Pattern applications have four tiers, prompted as Choose your configuration tier?:

Tier	Database	Server Lambda	Network	Backup vault
Standard	Instance `t4g.large`	1536 MB / 60 s	3 AZ, 1 NAT	standard
Lightweight	Instance `t4g.small`	512 MB / 30 s	2 AZ, 1 NAT	none
Resilient	Aurora v2 + CMK	2048 MB / 120 s	3 AZ, 3 NAT	resilient
Custom	You choose	You choose	You choose	You choose

Standard retains backups for 14 days with deletion protection on. Lightweight retains 7 days with deletion protection off. Resilient retains 30 days with customer-managed KMS encryption. Custom replaces the preset with seven prompts: database type, instance type (Instance only), backup retention, deletion protection, KMS encryption (Aurora only), Lambda memory, and Lambda timeout.

The six-option list (Standard, Lightweight, Resilient, Enterprise, Tinkerer, Custom) belongs to the plain application wizard reached with -t/--type. Pattern applications have four tiers and no Enterprise or Tinkerer option.

What the pattern provisions

Resource	Purpose
RDS PostgreSQL	Payload database (Instance or Aurora v2)
S3 assets bucket	Static build output served through CloudFront
S3 cache bucket	Next.js ISR cache
S3 media bucket	Payload uploads
DynamoDB table	Tag-to-path cache for ISR revalidation
SQS FIFO queue	Background revalidation, with a dead-letter queue
Lambda (server)	SSR, API routes, admin panel
Lambda (image)	`next/image` optimisation
Lambda (revalidation)	Processes the ISR queue
CloudFront	CDN with HTTPS, path routing, and caching

CloudFront routes four path patterns:

Path pattern	Origin	Cache policy
`/_next/static/*`	Assets bucket	`CACHING_OPTIMIZED`
`/_next/image*`	Image Lambda	`CACHING_OPTIMIZED`
`/api/*`	Server Lambda	`CACHING_DISABLED`
`/admin/*`	Server Lambda	`CACHING_DISABLED`
everything else	Server Lambda	`CACHING_DISABLED`

The generated infrastructure file

fjall/my-payload-site/infrastructure.ts looks like this:

#!/usr/bin/env node

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

const appName = "my-payload-site";
const app = App.getApp(appName, {
  network: {
    maxAzs: 3,
    natGateways: { count: 1 },
  },
  backup: { tier: "standard" },
});

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

app.addPattern(
  PatternFactory.build("MyPayloadSitePayload", {
    type: "payload",
    name: "my-payload-site",
    database: {
      type: "Instance",
      instanceType: "t4g.large",
      backupRetention: 14,
      deletionProtection: true,
    },
    compute: {
      server: {
        memorySize: 1536,
        timeout: 60,
      },
      imageOptimisation: {
        memorySize: 1536,
        timeout: 30,
      },
      revalidation: {
        memorySize: 768,
        timeout: 300,
      },
    },
  }),
);

The database and compute blocks are always written out, even when you accept every default, so the file shows you what you are getting rather than hiding it behind the pattern. storage, messaging, cdn and environment are the opposite: they appear only once you configure them. The values above are the Standard tier, which is also what set network and backup on App.getApp. Only server picks up the tier’s Lambda sizing; imageOptimisation and revalidation keep the construct defaults on every tier.

The first argument to PatternFactory.build is a derived construct id, toPascalCase(name) plus the pattern suffix, so my-payload-site yields MyPayloadSitePayload. fjall modify pattern and fjall remove pattern locate the statement by that id. Rename it by hand and the CLI can no longer find the pattern.

Edit the second argument to configure the pattern. See Configuration reference below.

What the CLI patches

fjall deploy rewrites the Payload project for Lambda before it builds. Every patch is idempotent, so repeated deploys are safe, and the CLI skips any file it does not find.

Packages

Installs @fjall/payload and @payloadcms/storage-s3.

Database adapter

Replaces the Postgres adapter in payload.config.ts and spreads Fjall’s CORS and CSRF defaults into buildConfig:

import { fjallPostgresAdapter, fjallDefaults } from "@fjall/payload";
import { migrations } from "./migrations";

export default buildConfig({
  ...fjallDefaults(),
  db: await fjallPostgresAdapter({
    migrationDir: "./src/migrations",
    prodMigrations: migrations,
  }),
});

fjallDefaults() locks CORS and CSRF to NEXT_PUBLIC_SERVER_URL when a custom domain is set, and stays permissive otherwise.

S3 media storage

Adds Fjall’s S3 plugin to src/plugins/index.ts:

import { awsS3Storage } from "@fjall/payload";

export const plugins: Plugin[] = [awsS3Storage()];

awsS3Storage() reads MEDIA_BUCKET_NAME and AWS_REGION from the Lambda environment and falls back to disk storage locally. It also patches src/collections/Media.ts to drop staticDir in production.

Next.js configuration

Adds output: 'standalone' for OpenNext and an outputFileTracingIncludes block that traces runtime dependencies Lambda would otherwise miss under pnpm.

Build-time guards

Payload pages that query the database during next build fail without a database connection. The CLI guards the website template’s pages:

File	Fix applied
`src/app/(frontend)/[slug]/page.tsx`	`generateStaticParams` returns `[]` at build
`src/app/(frontend)/posts/[slug]/page.tsx`	`generateStaticParams` returns `[]` at build
`src/app/(frontend)/posts/page/[pageNumber]/page.tsx`	`generateStaticParams` returns `[]` at build
`src/app/(frontend)/page.tsx`	`export const dynamic = 'force-dynamic'`
`src/app/(frontend)/posts/page.tsx`	`export const dynamic = 'force-dynamic'`
`src/app/(frontend)/search/page.tsx`	`export const dynamic = 'force-dynamic'`

These paths track the Payload website template layout. In a project with a different structure, guard your own build-time queries with isBuildTime() from @fjall/payload:

import { isBuildTime } from "@fjall/payload";

export async function generateStaticParams() {
  if (isBuildTime()) return [];
  // fetch data
}

Deploying

fjall deploy my-payload-site

Bare fjall deploy opens an application picker. The positional argument is the application name, not a tier and not a domain.

Pre-flight checks

The first deploy streams a checklist before any AWS call:

Detecting application pattern
Configuring Payload for AWS
Creating database migrations
Generating Payload import map
Building Next.js application
Synthesising infrastructure
Comparing template hashes
Validating Docker configuration
Validating SSM secrets

Approval gate

With changes pending, Fjall prints a deployment plan and asks Approve this plan and deploy?, defaulting to No. Rejecting the plan changes nothing. Pass --skip-confirmation or --auto-approve in CI. Resources marked for replacement or deletion trigger a separate typed-name consent step that no flag bypasses. The first deploy takes roughly 10 to 15 minutes because CloudFormation creates the VPC, database, and distribution. Later deploys update only what changed. If nothing changed, the run ends with Already up to date.

After the deploy

Find your URL

The CDN stack exports the distribution domain as <PatternName>DistributionDomainName. Read it from the deploy output or from the application status:

fjall status my-payload-site

Frontend: https://d1234567890.cloudfront.net
Admin panel: https://d1234567890.cloudfront.net/admin

Create the first admin user

Open /admin
The first-run screen prompts for the initial user
Enter an email address and password
Sign in

Verify the deployment

Admin panel loads at /admin
First admin user can be created
Media uploads land in S3
Content can be created and published
Published content renders on the frontend
Images load through /_next/image

Database migrations

Payload manages schema changes with migration files.

Generate a migration

npx payload migrate:create
git add src/migrations/
git commit -m "Add migrations"

Apply migrations

Migrations run on Lambda cold start via prodMigrations, which the CLI wires into the adapter for you:

db: await fjallPostgresAdapter({
  migrationDir: "./src/migrations",
  prodMigrations: migrations,
});

Generate and commit migrations before deploying a schema change. A deploy without them leaves the Lambda querying tables that do not exist.

Environment variables

Fjall injects these into the server Lambda. Do not set them yourself.

Variable	Value
`DATABASE_HOST`	RDS endpoint
`DATABASE_PORT`	Assigned port, not always 5432
`DATABASE_NAME`	Database name
`DATABASE_SSL`	`true`
`CACHE_BUCKET_NAME`	ISR cache bucket
`CACHE_BUCKET_REGION`	Stack region
`CACHE_DYNAMO_TABLE`	Tag cache table
`REVALIDATION_QUEUE_URL`	SQS queue URL
`REVALIDATION_QUEUE_REGION`	Stack region
`MEDIA_BUCKET_NAME`	Media uploads bucket
`NEXT_PUBLIC_SERVER_URL`	`https://<your-domain>`, only with a custom domain

Database credentials come from Secrets Manager, never from an environment variable. Add your own variables through the pattern’s environment block, which merges over the injected set.

Custom domain

Set domain and Fjall creates the ACM certificate and the Route53 alias record:

app.addPattern(
  PatternFactory.build("MyPayloadSitePayload", {
    type: "payload",
    name: "my-payload-site",
    domain: "cms.example.com",
  }),
);

To supply your own certificate instead, use the cdn block:

app.addPattern(
  PatternFactory.build("MyPayloadSitePayload", {
    type: "payload",
    name: "my-payload-site",
    cdn: {
      domainNames: ["cms.example.com"],
      certificateArn: "arn:aws:acm:us-east-1:123456789012:certificate/abc-123",
    },
  }),
);

The certificate must live in us-east-1 for CloudFront. Setting a domain also sets NEXT_PUBLIC_SERVER_URL, which locks Payload’s CORS and CSRF to that origin.

Configuration reference

Root options

Option	Type	Default	Description
`type`	`"payload"`	Required	Pattern type
`name`	string	Required	Pattern name, used for resource naming
`domain`	string	-	Custom domain, auto-creates certificate and DNS
`database`	object	-	Database configuration
`compute`	object	-	Per-Lambda configuration
`storage`	object	-	Per-bucket configuration
`messaging`	object	-	Revalidation queue configuration
`cdn`	object	-	Advanced CloudFront configuration
`environment`	`Record<string, string>`	-	Extra environment variables for the server Lambda

The config schema is strict. An unknown key fails validation before synth.

Database options

Option	Type	Default	Description
`type`	`"Instance" \| "Aurora"`	`"Instance"`	Database engine variant
`databaseName`	string	Derived	Database name
`databaseEngine`	string	`postgresql`	Database engine
`instanceType`	string	Tier preset	Instance class, Instance variant only
`allocatedStorage`	number	`100`	Storage in GiB, Instance variant only
`multiAz`	boolean	-	Multi-AZ deployment
`backupRetention`	number	`7`	Days of automated backups
`deletionProtection`	boolean	`true`	Prevent accidental deletion
`port`	number	Engine default	Database port
`databaseInsights`	object \| `false`	-	Database Insights configuration
`databaseInsights.mode`	`"standard" \| "advanced"`	-	Insights level
`databaseInsights.encryptionKey`	object	-	`{ awsManaged: true }` or `{ useCMK: true }`
`proxy`	object \| `false`	-	RDS Proxy connection pooling
`encryption`	object	-	Storage encryption key
`credentials`	object	-	Username and rotation
`snapshotIdentifier`	string	-	Snapshot to restore from
`snapshotUsername`	string	-	Master username from the snapshot

databaseInsights accepts only mode and encryptionKey. There is no retentionPeriod key, and passing one fails validation with Unrecognized key: retentionPeriod.

Aurora adds writer and readers. Instance adds readReplica. See the DatabaseFactory reference for the full property set.

Compute options

Each of server, imageOptimisation, and revalidation accepts the same three keys.

Option	Type	Default	Description
`server.memorySize`	number	`1536`	Server Lambda memory in MB
`server.timeout`	number	`30`	Server Lambda timeout in seconds
`server.ephemeralStorageSize`	number	`512`	Ephemeral storage in MiB
`imageOptimisation.memorySize`	number	`1536`	Image Lambda memory in MB
`imageOptimisation.timeout`	number	`30`	Image Lambda timeout in seconds
`revalidation.memorySize`	number	`768`	Revalidation Lambda memory in MB
`revalidation.timeout`	number	`300`	Revalidation Lambda timeout in seconds

The defaults above are the construct’s. A tier preset overrides the server memory and timeout at create time, so a Standard application is written with 1536 MB and 60 seconds.

Storage options

Option	Type	Default	Description
`assets.versioned`	boolean	`false`	Version the build-output bucket
`cache.versioned`	boolean	`false`	Version the ISR cache bucket
`media.versioned`	boolean	Backup tier	Version the uploads bucket

The media bucket follows the application’s backup tier, so versioning is on at Resilient and Enterprise. Assets and cache stay unversioned at every tier because both churn, and each carries the fjall:s3:versioning-exempt tag saying so (build-output and isr-cache), so a posture scan reads the choice as deliberate; versioned: true drops the tag. An explicit value always wins:

storage: {
  media: { versioned: true },
}

Messaging options

Option	Type	Default	Description
`messaging.revalidationQueue.visibilityTimeout`	number	Revalidation timeout	SQS visibility timeout in seconds
`messaging.revalidationQueue.messageRetentionPeriod`	number	`345600`	Message retention in seconds
`messaging.revalidationQueue.maxMessageSize`	number	`262144`	Maximum message size in bytes
`messaging.revalidationQueue.deadLetterQueue`	object \| `false`	`{ enabled: true, maxReceiveCount: 3 }`	Dead-letter queue

CDN options

Option	Type	Default	Description
`domainNames`	string[]	-	Custom domain names
`certificateArn`	string	-	ACM certificate ARN, must be in `us-east-1`

Prefer the root-level domain for a simple setup. The cdn block is for supplying a certificate you already manage.

Full example

app.addPattern(
  PatternFactory.build("MyPayloadSitePayload", {
    type: "payload",
    name: "my-payload-site",
    domain: "cms.example.com",

    database: {
      type: "Aurora",
      databaseName: "payload",
      deletionProtection: true,
      backupRetention: 30,
      databaseInsights: { mode: "advanced" },
    },

    compute: {
      server: { memorySize: 2048, timeout: 60 },
      imageOptimisation: { memorySize: 1536 },
    },

    storage: {
      media: { versioned: true },
    },

    environment: {
      LOG_LEVEL: "info",
    },
  }),
);

Going beyond the pattern

The pattern is a composition of the same factories you can call directly. Replace the pattern statement with individual factory calls when you need to:

Add resources the pattern does not create, such as a worker queue or Redis
Customise networking, for example VPC peering or private subnets
Share a database between several applications
Narrow IAM permissions past the pattern’s defaults

The composition looks like this. It is a starting point, not a byte-for-byte reproduction: the pattern also wires environment variables, IAM grants, and CloudFront behaviours that you would rebuild by hand.

#!/usr/bin/env node

import {
  App,
  DatabaseFactory,
  StorageFactory,
  ComputeFactory,
  CdnFactory,
  MessagingFactory,
  Code,
} from "@fjall/components-infrastructure";

const appName = "my-payload-site";
const app = App.getApp(appName, { network: { maxAzs: 3 } });

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

const assetsBucket = app.addStorage(StorageFactory.build("Assets", {}));
const cacheBucket = app.addStorage(StorageFactory.build("Cache", {}));
const mediaBucket = app.addStorage(StorageFactory.build("Media", {}));

const tagCache = app.addDatabase(
  DatabaseFactory.build("TagCache", {
    type: "DynamoDB",
    partitionKey: { name: "tag", type: "S" },
    sortKey: { name: "path", type: "S" },
    globalSecondaryIndexes: [
      {
        indexName: "revalidate",
        partitionKey: { name: "path", type: "S" },
        sortKey: { name: "revalidatedAt", type: "N" },
      },
    ],
  }),
);

const revalidationQueue = app.addMessaging(
  MessagingFactory.build("Revalidation", {
    type: "queue",
    queueType: "fifo",
    contentBasedDeduplication: true,
    deadLetterQueue: { enabled: true, maxReceiveCount: 3 },
  }),
);

const server = app.addCompute(
  ComputeFactory.build("Server", {
    type: "lambda",
    deployment: "code",
    handler: "index.handler",
    code: Code.fromAsset("../../.open-next/server-functions/default"),
    memorySize: 1536,
    timeout: 30,
    connections: [
      database,
      assetsBucket,
      cacheBucket,
      mediaBucket,
      tagCache,
      revalidationQueue,
    ],
  }),
);

const imageOptimiser = app.addCompute(
  ComputeFactory.build("ImageOptimiser", {
    type: "lambda",
    deployment: "code",
    handler: "index.handler",
    code: Code.fromAsset("../../.open-next/image-optimization-function"),
    memorySize: 1536,
    timeout: 30,
    connections: [assetsBucket],
  }),
);

app.addCdn(
  CdnFactory.build("Cdn", {
    originType: "auto",
    origin: server,
    cachePolicy: "CACHING_DISABLED",
    defaultAllowedMethods: "ALL",
    forwardHostHeader: true,
    behaviours: [
      {
        pathPattern: "/_next/static/*",
        origin: assetsBucket,
        cachePolicy: "CACHING_OPTIMIZED",
      },
      {
        pathPattern: "/_next/image*",
        origin: imageOptimiser,
        cachePolicy: "CACHING_OPTIMIZED",
      },
      {
        pathPattern: "/api/*",
        origin: server,
        cachePolicy: "CACHING_DISABLED",
        allowedMethods: "ALL",
      },
      {
        pathPattern: "/admin/*",
        origin: server,
        cachePolicy: "CACHING_DISABLED",
        allowedMethods: "ALL",
      },
    ],
  }),
);

Once broken out, add resources with fjall add or by editing the file directly. See Add Resources.

Troubleshooting

Build fails with “Error occurred prerendering page”

A page queries the database during next build. The CLI guards the website template’s pages automatically, so first update the CLI:

npm update -g fjall
fjall deploy my-payload-site

For a custom page, guard the query with isBuildTime() from @fjall/payload.

403 on admin panel actions

Payload’s CSRF list does not include the origin you are calling from. fjallDefaults() sets cors and csrf correctly, so keep the spread first in buildConfig and do not redeclare either key after it:

export default buildConfig({
  ...fjallDefaults(),
  // your config, with no cors or csrf keys
});

Media uploads disappear

The Media collection is still writing to the local filesystem. Keep awsS3Storage() in the plugins array and keep staticDir behind isProduction() in src/collections/Media.ts.

”relation does not exist”

Migrations were never generated or never committed:

npx payload migrate:create
git add src/migrations/
git commit -m "Add migrations"
fjall deploy my-payload-site

`fjall modify pattern` cannot find the pattern

The construct id in PatternFactory.build was renamed. Restore it to toPascalCase(name) plus Payload, so my-payload-site becomes MyPayloadSitePayload.

Costs

The database and the NAT gateway are always-on, so they set the floor. Lambda, S3 and CloudFront are usage-priced and stay small on a low-traffic site. Indicative us-east-1 on-demand list prices, excluding data transfer:

Resource	Standard tier	Lightweight tier
RDS PostgreSQL	~$188 (`t4g.large`, Multi-AZ)	~$47 (`t4g.small`, Multi-AZ)
RDS storage	~$23 (100 GiB gp3, Multi-AZ)	~$23 (100 GiB gp3, Multi-AZ)
NAT gateway	~$33	~$33
Lambda	~ $0 to$ 5 (pay per request)	~ $0 to$ 5
S3	~ $0.50 to$ 2	~ $0.50 to$ 2
CloudFront	~ $1 to$ 5	~ $1 to$ 5
Total	~$250	~$110

No payload tier scaffolds t4g.micro. Lightweight writes t4g.small and Standard writes t4g.large, and neither writes multiAz, so the RDS construct’s own default takes over and both come up Multi-AZ, roughly doubling the instance and storage lines. Add multiAz: false to the database block yourself if you do not need the standby.

Set database.type: "Aurora" for Aurora Serverless v2, which scales down when idle and can lower the database line for bursty or low-traffic sites. Run fjall costs --app <name> once deployed for figures from your own account.

Next Steps

Deploy Application

Flags, targets, and the approval gate

Custom Domain

Point a domain at your CloudFront distribution

Add Resources

Extend the application with more AWS services

Database Factory

Every database property the pattern exposes

Static Site Pattern

Deploy a pre-built folder instead

CI/CD

Automate deployments with Buildkite

Fjall:

Create Application - Scaffolding options
Compute Factory - Lambda and ECS configuration
Storage Factory - S3 bucket options
CDN Factory - CloudFront behaviours
Network Factory - VPC and networking

External:

Payload CMS docs - Official Payload documentation
OpenNext - Next.js to AWS Lambda
Aurora Serverless v2 - AWS Aurora documentation

​Overview

​Prerequisites

​Quick start

​1. Scaffold a Payload project

​2. Create the Fjall application

​3. Deploy

​Choosing a pattern

​Choosing a tier

​What the pattern provisions

​The generated infrastructure file

​What the CLI patches

​Packages

​Database adapter

​S3 media storage

​Next.js configuration

​Build-time guards

​Deploying

​Pre-flight checks

​Approval gate

​After the deploy

​Find your URL

​Create the first admin user

​Verify the deployment

​Database migrations

​Generate a migration

​Apply migrations

​Environment variables

​Custom domain

​Configuration reference

​Root options

​Database options

​Compute options

​Storage options

​Messaging options

​CDN options

​Full example

​Going beyond the pattern

​Troubleshooting

​Build fails with “Error occurred prerendering page”

​403 on admin panel actions

​Media uploads disappear

​”relation does not exist”

​fjall modify pattern cannot find the pattern

​Costs

​Next Steps

Deploy Application

Custom Domain

Add Resources

Database Factory

Static Site Pattern

CI/CD

​Related documentation

Overview

Prerequisites

Quick start

1. Scaffold a Payload project

2. Create the Fjall application

3. Deploy

Choosing a pattern

Choosing a tier

What the pattern provisions

The generated infrastructure file

What the CLI patches

Packages

Database adapter

S3 media storage

Next.js configuration

Build-time guards

Deploying

Pre-flight checks

Approval gate

After the deploy

Find your URL

Create the first admin user

Verify the deployment

Database migrations

Generate a migration

Apply migrations

Environment variables

Custom domain

Configuration reference

Root options

Database options

Compute options

Storage options

Messaging options

CDN options

Full example

Going beyond the pattern

Troubleshooting

Build fails with “Error occurred prerendering page”

403 on admin panel actions

Media uploads disappear

”relation does not exist”

`fjall modify pattern` cannot find the pattern

Costs

Next Steps

Related documentation