Fjall Docs — deploy AWS infrastructure into your own account

Prerequisites

Complete these before deploying:

Create an application, so an infrastructure.ts exists in your project
Authenticate with Fjall by running fjall login, or set FJALL_API_KEY for CI/CD
Connect an AWS account by running fjall connect

fjall deploy enforces both gates before it touches AWS. An unauthenticated run stops with Authentication required. Run 'fjall login' first.

Deploy your application

Run this from your project root:

fjall deploy api

Replace api with your application name. The one command builds the container image, synthesises infrastructure, and applies the change. The positional argument is always an application name. Tier deploys are separate noun-verb commands: fjall org deploy, fjall platform deploy and fjall account deploy. Passing a tier word to fjall deploy stops before authentication with a teaching error, so nothing is validated and nothing is deployed.

What happens during a deploy

At a TTY, Fjall renders a step checklist, streams live CloudFormation events, and stops for approval before applying changes.

Step checklist

Steps that do not apply to your application drop out. An application with no CDN never shows the CDN step.

Step	What it covers
Authenticating with AWS	Mints credentials for the resolved deployment target
Preparing deployment	Detects the application pattern and runs the pre-deployment checklist below
Verifying target readiness	Probes the target account and region
Bootstrapping AWS environment	Confirms the CDK bootstrap stack is present
Deploying network infrastructure	VPC, subnets, security groups, load balancer
Deploying storage infrastructure	S3 buckets, ECR repositories
Deploying messaging infrastructure	SQS queues, SNS topics, EventBridge rules
Deploying database infrastructure	RDS instances, Aurora clusters, ClickHouse
Docker operations	Builds and pushes the container image
Tagging container images	Applies the content-addressed image tag in ECR
Deploying compute infrastructure	ECS services and Lambda functions
Deploying us-east-1 certificate infrastructure	ACM certificates for CloudFront
Deploying cdn infrastructure	CloudFront distribution

Pre-deployment checklist

A streaming checklist runs before synthesis. Steps that do not apply drop out.

✔ 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

Synthesis also checks engine compatibility before anything is deployed.

Live progress

Each stack streams its own CloudFormation resource events in an operation box, with a progress bar and a per-resource table. The Docker build, the ECS rollout, and OpenNext builds get their own boxes. When storage, messaging, and database deploy concurrently, a switchable parallel panel replaces the single box. If nothing changed since the last deploy, the run ends before any gate with Already up to date — no changes since last deploy.

Confirmations

Up to four prompts can appear, in this order.

Prompt	When it appears	Default	Bypassed by
`Deploy anyway?`	Required SSM secrets are missing. Fjall lists each name and its expected path	No	Nothing. Answering No aborts the deploy
`Approve this plan and deploy?`	The deploy has changes. A bordered card renders the resource-level plan first	No	`--skip-confirmation`, `--auto-approve`
Destructive-change consent	The plan replaces or destroys a resource. Per-resource verb plus a typed resource name	None	Nothing. No flag skips this ceremony
`Restart N service(s) to reconnect now?`	The deploy replaced the database	Yes	`--skip-confirmation`, after which the engine restarts them for you

The change plan

The approval gate is engaged by default at a TTY, on any deploy that has changes.

┌───────────────────────────────────────────────────────────────────────────┐
│ Deployment plan for api                                                   │
│                                                                           │
│ 2 to create, 1 to replace, 1 to destroy (2 destructive, 1 with data loss) │
│                                                                           │
│ + create  AWS::EC2::SecurityGroup  ApiNetwork/AlbSg                       │
│ + create  AWS::ECS::Cluster  ApiCompute/Cluster                           │
│ ± replace AWS::ECS::Service  ApiCompute/Service                           │
│ - delete  AWS::RDS::DBInstance  ApiDatabase/Db (data loss)                │
│                                                                           │
│ ! This plan includes destructive changes (replace or destroy).            │
└───────────────────────────────────────────────────────────────────────────┘

? Approve this plan and deploy?  ▸ Yes  No

Change symbols: + create, ~ update, ± replace, - delete, > read. Rejecting the plan prints ⊘ Plan rejected — deployment cancelled, nothing changed. Declining a destructive consent prints ⊘ Destructive changes declined — deployment withheld, nothing was applied. Non-interactive and CI runs show no plan unless you pass --plan or --require-approval. See Destructive Changes for the consent ceremony.

Deployment options

Skip the prompts

fjall deploy api --skip-confirmation

This drops the plan approval and the post-deploy restart prompt. It does not satisfy the destruction gate or the missing-secrets prompt. For CI/CD pipelines, force plain output:

fjall deploy api --non-interactive

Infrastructure only

Apply infrastructure changes without rebuilding the container:

fjall deploy api --infra-only

Code only

Rebuild and redeploy the container without touching infrastructure:

fjall deploy api --deploy-only

Skip the build

Reuse an already-pushed image, paired with --deploy-only:

fjall deploy api --deploy-only --skip-build

Roll forward or back to a known image

Deploy an existing image tag. This skips the build and implies --deploy-only:

fjall deploy api --image-tag api-sha-a1b2c3d4e5f6

Fjall image tags are content-addressed: <service>-sha-<12 hex characters of the image digest>. List the tags an application has shipped with fjall releases api, or read them from its ECR repository. Tags like v1.4.2 are not produced by Fjall builds and will not resolve.

Select the build-arg tier

-e, --environment <env> chooses which .env.<stage> file supplies Docker build args:

fjall deploy api -e production

-e, --environment does not select an AWS account, a region, a target, or the synthesis environment. The account comes from the active deployment target (fjall target set <name>, or --target <name> per deploy). The synthesis environment, which decides every removal policy, is derived from the target account’s own record. See Understanding Profiles.

Verbose output

fjall deploy api --verbose

Common deploy options

Option	Description
`--infra-only`	Deploy only infrastructure, skipping the code deployment
`--deploy-only`	Deploy only code, skipping infrastructure
`--skip-build`	Skip the Docker build, for use with `--deploy-only`
`--skip-migrations`	Skip database migrations during this deployment
`--skip-confirmation`	Skip the plan approval and post-deploy restart prompts
`--non-interactive`	Force plain CLI output with no Ink UI
`-e, --environment <env>`	Select the `.env.<stage>` build-arg tier
`-f, --force`	Redeploy all stacks even when no infrastructure changes are detected
`-v, --verbose`	Enable verbose logging
`--target <name>`	Override the active deployment target for this deploy
`--region <region>`	Deploy to a specific region within the target’s account
`--all-regions`	Deploy to every region configured for the target’s account
`--image-tag <tag>`	Deploy an existing image tag, skipping the build
`--plan`	Print the change plan and stop before any mutation
`--auto-approve`	Approve the computed plan without prompting
`--deployment-id <id>`	Deployment record ID used for progress tracking

fjall deploy carries the full flag surface, including the approval-token, destructive-consent, build-arg, and build-secret families.

Cascade control belongs to the organisation tier. --no-cascade is registered only on fjall org deploy, never on an application deploy.

After deployment

Inspect your resources

List the resources declared in the application’s infrastructure.ts:

fjall list --app api

fjall list reads the file on disk, not CloudFormation. Two commands give the wider view: fjall status prints a name and health table of every application plus a summary line, and fjall apps lists the applications in your organisation.

View logs

Fjall never writes ~/.aws/credentials, so run AWS commands through the CLI’s minted credentials:

# Find the log group for your service
fjall aws exec --app api -- aws logs describe-log-groups --query "logGroups[].logGroupName"

# Tail it
fjall aws exec --app api -- aws logs tail <log-group> --follow

The ECS service’s Logs tab in the AWS console shows the same stream.

Track costs

# Current spend
fjall costs --mode summary --app api

# 30-day breakdown
fjall costs --mode breakdown --days 30

Update an application

Change	Command
Application code only	`fjall deploy api --deploy-only`
Infrastructure, after editing `infrastructure.ts`	`fjall deploy api`
Rotated secrets, with no code or infra change	`fjall rollout api`

Roll back

A rollback re-registers each service against images that already exist in ECR. Nothing is rebuilt and infrastructure is not re-synthesised.

# See the release history
fjall releases api

# Roll back to the previous release
fjall rollback api

# Roll back to a specific release number
fjall rollback api --to 11

To pin a single service to a known image instead, use fjall deploy api --image-tag <tag>. See releases and rollback for the full behaviour.

Troubleshooting

When a deploy fails, CloudFormation rolls the stack back and names the failing resource.

Read the error message. It names the resource that failed.
Re-run with --verbose for detailed logs.
Fix the underlying issue and redeploy.

Common issues

Error	Fix
`User does not have permission to create IAM roles`	Confirm your AWS role has the required IAM permissions. See Permission errors.
`You have reached the maximum number of VPCs`	Request a quota increase, or deploy to a different region with `--region`. See Limit errors.
`Stack with name '...' already exists`	Choose a different application name, or destroy the existing stack first.
`This assembly ... requires deploy engine >= X.0.0`	Your installed CLI is older than your application’s constructs. Upgrade with `npm install -g fjall@X`. See Engine Compatibility.

The deployment error reference covers the classified CloudFormation and ECS failures in detail.

Next Steps

A first deployment typically takes 10 to 15 minutes while AWS provisions resources. Later updates are faster.

Add Resources

Extend your application with databases, storage, and more

Deploy Reference

The complete fjall deploy flag surface and subcommands

Destructive Changes

Understand the consent ceremony before a replace or destroy

Set Up CI/CD

Automate deployments from your pipeline

Install & Setup

Application Deploy

Deployment Errors

Organisation Setup

Organisation Deploy

Deploy Application

Prerequisites

Deploy your application

What happens during a deploy

Step checklist

Pre-deployment checklist

Live progress

Confirmations

The change plan

Deployment options

Skip the prompts

Infrastructure only

Code only

Skip the build

Roll forward or back to a known image

Select the build-arg tier

Verbose output

Common deploy options

After deployment

Inspect your resources

View logs

Track costs

Update an application

Roll back

Troubleshooting

Common issues

Next Steps

Add Resources

Deploy Reference

Destructive Changes

Set Up CI/CD

​Prerequisites

​Deploy your application

​What happens during a deploy

​Step checklist

​Pre-deployment checklist

​Live progress

​Confirmations

​The change plan

​Deployment options

​Skip the prompts

​Infrastructure only

​Code only

​Skip the build

​Roll forward or back to a known image

​Select the build-arg tier

​Verbose output

​Common deploy options

​After deployment

​Inspect your resources

​View logs

​Track costs

​Update an application

​Roll back

​Troubleshooting

​Common issues

​Next Steps

Add Resources

Deploy Reference

Destructive Changes

Set Up CI/CD

Prerequisites

Deploy your application

What happens during a deploy

Step checklist

Pre-deployment checklist

Live progress

Confirmations

The change plan

Deployment options

Skip the prompts

Infrastructure only

Code only

Skip the build

Roll forward or back to a known image

Select the build-arg tier

Verbose output

Common deploy options

After deployment

Inspect your resources

View logs

Track costs

Update an application

Roll back

Troubleshooting

Common issues

Next Steps