Fjall Docs — deploy AWS infrastructure into your own account

Overview

fjall build builds Docker images and pushes them to Amazon ECR. Use it in CI/CD pipelines that separate the build step from the deploy step, so you can test the exact image you are about to ship. The command is non-interactive by design. It prints a three-step progress stream and, with --output-image-url, a machine-readable block your pipeline can parse.

Prerequisites

Requirement	Why
Signed in to Fjall	Run `fjall login`. Fjall mints the AWS credentials itself, so no `aws` profile is required
Project bound to an org	`fjall build` refuses if the project’s `organisation` binding does not match your login
Network stack deployed	Run `fjall deploy <app>` at least once. The ECR repository lives in the Network stack
Docker running	The Docker daemon must be running on the build host

Usage

fjall build <app> [service] [options]

Arguments

Argument	Description	Required
`app`	Application name	Yes
`service`	Build only this service instead of every service	No

Options

Option	Description	Example
`--target <target>`	Docker build target stage for multi-stage Dockerfiles	`--target production`
`--output-image-url`	Print the pushed image URLs in a machine-readable block	`--output-image-url`
`--build-arg <KEY=VALUE>`	Public build-time arg, repeatable, highest precedence	`--build-arg NEXT_PUBLIC_API_URL=https://…`
`--build-secret <id=ID,ssm=PATH>`	Build secret reference, repeatable, never baked into layers	`--build-secret id=npm,ssm=/api/npm-token`
`-v, --verbose`	Show detailed output	`-v`
`--non-interactive`	Force plain CLI output	`--non-interactive`

--target on fjall build is the Docker build target stage. --target on fjall deploy is the deployment target (account and region). Same flag name, two different meanings.

Agent flags

These flags shape output for AI-agent and scripted callers.

Flag	Description
`--agent`	Enable agent output mode
`--budget <level>`	Output budget: `minimal`, `compact`, or a token count
`--fields <fields>`	Select exactly these output fields
`--full`	Disable content truncation

Basic usage

Build every service in an application:

fjall build api

Build one service:

fjall build api web

Build a named Dockerfile stage:

fjall build api --target production

Build arguments

--build-arg bakes a public value into the image at build time. It is repeatable, and it is the highest tier of the resolution ladder:

--build-arg  >  shell env var of the same name  >  .env.production  >  .env  >  the value declared in infrastructure.ts

fjall build dashboard \
  --build-arg NEXT_PUBLIC_API_URL=https://api.example.com \
  --build-arg NEXT_PUBLIC_ENV=production

Two rules govern which keys reach the build:

A key is emitted when your infrastructure.ts declares it, when you pass it via --build-arg, or when a key prefixed VITE_, NEXT_PUBLIC_ or PUBLIC_ is found in a parsed .env file.
Shell environment variables override the value of an already-declared key. They never introduce a new key, so arbitrary host environment cannot leak into the image.

An empty string at any tier counts as absent and falls through to the next tier.

A build arg is baked into the image layer and readable by anyone who can pull it. Use --build-secret for anything private.

Build secrets

--build-secret passes a value to the build through BuildKit’s secret mount, so it never lands in an image layer. It is repeatable, and each token is a comma-separated list of key=value pairs: an id plus exactly one source.

Key	Meaning
`id`	The BuildKit secret id your Dockerfile mounts
`ssm`	SSM Parameter Store path
`secretsManager`	Secrets Manager secret name
`field`	Optional JSON field inside a Secrets Manager secret
`env`	Environment variable on the build host

fjall build api \
  --build-secret id=npm,ssm=/api/production/NPM_TOKEN \
  --build-secret id=sentry,secretsManager=api-sentry,field=token

Mount it in your Dockerfile:

RUN --mount=type=secret,id=npm \
    NPM_TOKEN="$(cat /run/secrets/npm)" npm ci

Give each reference exactly one source: ssm, secretsManager or env. A malformed token fails the whole command before any AWS work starts, so a typo never reaches a build silently.

CI/CD workflow

The build command suits pipelines that:

Build and push the image.
Run tests against the pushed image.
Deploy that exact image without rebuilding.

fjall ci run build <target> [service] wraps this command with a resolved deployment target and CI deploy-token credentials. See fjall ci and the CI/CD integration guide.

Example: GitHub Actions

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      image_url: ${{ steps.build.outputs.image_url }}
      image_tag: ${{ steps.build.outputs.image_tag }}
    steps:
      - uses: actions/checkout@v4

      - name: Build and push
        id: build
        run: |
          fjall build api --output-image-url --non-interactive | tee build.log
          IMAGE_URL=$(sed -n 's/^IMAGE_URL=//p' build.log)
          echo "image_url=$IMAGE_URL" >> "$GITHUB_OUTPUT"
          echo "image_tag=${IMAGE_URL##*:}" >> "$GITHUB_OUTPUT"

  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Run tests
        env:
          IMAGE_URL: ${{ needs.build.outputs.image_url }}
        run: docker run "$IMAGE_URL" npm test

  deploy:
    needs: [build, test]
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        env:
          IMAGE_TAG: ${{ needs.build.outputs.image_tag }}
        run: fjall deploy api --image-tag "$IMAGE_TAG" --non-interactive

--image-tag deploys the image the build step pushed, skipping the build and implying --deploy-only. It applies one tag family across the application’s services, so it fits applications whose services build from a single build group. For applications with independent build groups, deploy normally with fjall deploy api.

Example: Buildkite

steps:
  - label: "Build"
    key: "build"
    command: |
      fjall build api --output-image-url --non-interactive | tee build.log
      buildkite-agent meta-data set image_url "$(sed -n 's/^IMAGE_URL=//p' build.log)"

  - label: "Test"
    depends_on: "build"
    command: |
      docker run "$(buildkite-agent meta-data get image_url)" npm test

  - label: "Deploy"
    depends_on: "test"
    command: |
      IMAGE_URL="$(buildkite-agent meta-data get image_url)"
      fjall deploy api --image-tag "${IMAGE_URL##*:}" --non-interactive

Output

Standard output

Building Docker image(s) for: api
  Target service: web

==> [1/3] Authenticating with AWS
<== [1/3] Authenticating with AWS (1.4s)

==> [2/3] Getting ECR repository
<== [2/3] Getting ECR repository (0.9s)

==> [3/3] Building and pushing Docker images
<== [3/3] Building and pushing Docker images (1m 12s)

── Summary ────────────────────────────────────────
  Result:   ✓ api built successfully
  Duration: 1m 15s
  Images:   web → web-sha-a1b2c3d4e5f6

Next steps:
  Run tests: docker run 123456789012.dkr.ecr.eu-west-1.amazonaws.com/api:web-sha-a1b2c3d4e5f6 npm test
  Deploy this build: fjall deploy api --image-tag web-sha-a1b2c3d4e5f6

The Deploy this build line appears only when every built artefact shares one digest. When services build from separate build groups, the last line reads Deploy: fjall deploy api instead. Image tags follow <service>-sha-<12 hex characters>, with a -<target> segment folded in for a multi-stage service. The tag identifies the service and the content of the build, not the git ref, so there is no --tag flag to override it.

Machine-readable output

Pass --output-image-url to print a parseable block:

============================================================
IMAGE_URL=123456789012.dkr.ecr.eu-west-1.amazonaws.com/api:web-sha-a1b2c3d4e5f6
IMAGE service=web tag=web-sha-a1b2c3d4e5f6 digest=sha256:0f3a… uri=123456789012.dkr.ecr.eu-west-1.amazonaws.com/api:web-sha-a1b2c3d4e5f6
============================================================

Line	Contents
`IMAGE_URL`	The first pushed image URL
`ALL_IMAGE_URLS`	Comma-separated list, printed only when more than one service was built
`IMAGE …`	One line per built artefact, with `service`, `tag`, `digest` and `uri`

Parse the per-service IMAGE lines when you need a specific service’s tag. IMAGE_URL is the first artefact, not a summary of the build.

Docker build targets

If your Dockerfile uses multi-stage builds with named targets:

FROM node:24 AS base
# ...

FROM base AS development
# ...

FROM base AS production
# ...

Build a specific stage:

fjall build api --target production

Troubleshooting

ECR repository not found

ECR repository not found in stack outputs (build). Looking for export: ApiEcrRepositoryName. Ensure Network stack has been deployed.

Cause: the application’s Network stack has never been deployed, so the ECR repository and its CloudFormation export do not exist. The export name is the PascalCase form of the application name plus EcrRepositoryName. Fix: deploy the infrastructure once.

fjall deploy api --infra-only

Docker build failed

Error: Docker build failed: ...

Cause: a Dockerfile error, a missing dependency, or an unmounted build secret. Fix: reproduce the build locally, then re-run.

docker build -t api-test .

AWS account ID unavailable

Error: AWS authentication succeeded but account ID is unavailable

Cause: the Fjall session resolved but the target’s AWS identity did not. Fix: re-authenticate and confirm the active deployment target.

fjall login
fjall target get

Fjall derives every AWS profile in memory from your organisation config. Do not run aws sso login or hand-edit ~/.aws/config. See Understanding profiles.

Wrong organisation

Refusing to build: this project's fjall-config.json records organisation Acme (org_abc123)
as its home, but the credential in use belongs to Northwind (org_xyz789). Nothing was
created, synthesised or deployed.

Cause: the organisation binding in fjall-config.json does not match the organisation your credential belongs to. The gate refuses only on a proven mismatch, and it runs before the first AWS call. Fix: authenticate as the bound organisation, or, if the project really is moving, rebind it by name.

# Sign in as the organisation the project is bound to
fjall login

# Or re-bind the project to the organisation the credential belongs to
fjall org bind --org org_xyz789 --force

Next Steps

Deploy an application

Ship the image you just pushed

fjall deploy

Full reference for the deploy command, including --image-tag

fjall ci

Run builds and deploys from a CI pipeline

CI/CD integration

Pipeline templates, tokens, and exit codes

Core Commands

Infrastructure Codemods

Insights

Management Commands

Build & CI

Environments & Data

Diagnostics & Recovery

Authentication

Agent Mode

fjall build

Overview

Prerequisites

Usage

Arguments

Options

Agent flags

Basic usage

Build arguments

Build secrets

CI/CD workflow

Example: GitHub Actions

Example: Buildkite

Output

Standard output

Machine-readable output

Docker build targets

Troubleshooting

ECR repository not found

Docker build failed

AWS account ID unavailable

Wrong organisation

Next Steps

Deploy an application

fjall deploy

fjall ci

CI/CD integration

​Overview

​Prerequisites

​Usage

​Arguments

​Options

​Agent flags

​Basic usage

​Build arguments

​Build secrets

​CI/CD workflow

​Example: GitHub Actions

​Example: Buildkite

​Output

​Standard output

​Machine-readable output

​Docker build targets

​Troubleshooting

​ECR repository not found

​Docker build failed

​AWS account ID unavailable

​Wrong organisation

​Next Steps

Deploy an application

fjall deploy

fjall ci

CI/CD integration

Overview

Prerequisites

Usage

Arguments

Options

Agent flags

Basic usage

Build arguments

Build secrets

CI/CD workflow

Example: GitHub Actions

Example: Buildkite

Output

Standard output

Machine-readable output

Docker build targets

Troubleshooting

ECR repository not found

Docker build failed

AWS account ID unavailable

Wrong organisation

Next Steps