Fjall Docs — Deploy Production-Ready AWS Infrastructure in Minutes

Overview

fjall build builds Docker images and pushes them to Amazon ECR. Use it in CI/CD workflows that separate the build and deploy steps.

Prerequisites

Requirement	Why
Infrastructure deployed	Run `fjall deploy <app>` at least once to create the ECR repository
Docker running	The Docker daemon must be running locally
AWS credentials	Valid AWS credentials with ECR access

Usage

fjall build <app> [service] [options]

Arguments

Argument	Description	Required
`app`	Application name	Yes
`service`	Specific service to build	No

Options

Option	Description	Example
`--target <target>`	Docker build target stage	`--target production`
`--output-image-url`	Print the image URL for CI capture	`--output-image-url`
`-v, --verbose`	Show detailed output	`-v`
`--non-interactive`	Force plain CLI output	`--non-interactive`

Basic Usage

Build all services in an application:

fjall build api

Build a specific service:

fjall build api web

CI/CD Workflow

The build command suits CI/CD pipelines that:

Build and push images.
Run tests against the built image.
Deploy with the pre-built image.

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
        run: |
          docker run ${{ needs.build.outputs.image_url }} npm test

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

--image-tag deploys the exact image the build step pushed, without rebuilding. It applies one tag family across the app’s services, so it suits apps whose services build from a single build group — the build output offers the --image-tag next step only when that holds. Otherwise deploy normally (fjall deploy api).

Example: Buildkite

steps:
  - label: "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

[Authenticating with AWS] Starting...
[Authenticating with AWS] ✓ completed
[Getting ECR repository] Starting...
[Getting ECR repository] ✓ api-ecr
[Building and pushing Docker images] Starting...
  [Docker] Building image...
  [Docker] Pushing to ECR...
[Building and pushing Docker images] ✓ completed

Build completed successfully!

Pushed images:
  123456789.dkr.ecr.ap-southeast-2.amazonaws.com/api-ecr:api-sha-abc123def456

Next steps:
  Run tests: docker run 123456789.dkr.ecr.ap-southeast-2.amazonaws.com/api-ecr:api-sha-abc123def456 npm test
  Deploy this build: fjall deploy api --image-tag api-sha-abc123def456

With —output-image-url

When you pass --output-image-url, the command prints machine-readable values:

============================================================
IMAGE_URL=123456789.dkr.ecr.ap-southeast-2.amazonaws.com/api-ecr:api-sha-abc123def456
IMAGE service=api tag=api-sha-abc123def456 digest=sha256:0f3a… uri=123456789.dkr.ecr.ap-southeast-2.amazonaws.com/api-ecr:api-sha-abc123def456
============================================================

IMAGE_URL contains the last built image; ALL_IMAGE_URLS (a comma-separated list) is added when multiple services build. One IMAGE service=<name> tag=<tag> digest=<digest> uri=<uri> line is printed per built artefact — parse these when you need per-service tags.

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 target:

fjall build api --target production

Troubleshooting

ECR Repository Not Found

Error: ECR repository not found. Looking for export: apiEcrRepositoryName.
Ensure infrastructure has been deployed first with 'fjall deploy'.

Solution: deploy the infrastructure first.

fjall deploy api --infra-only

Docker Build Failed

Error: Docker build failed: ...

Cause: Dockerfile error or missing dependencies. Solution: test your Docker build locally first.

docker build -t test .

Authentication Failed

Error: Failed to get AWS account ID

Cause: invalid or expired AWS credentials. Solution: re-authenticate.

fjall login
# or
aws sso login

Core Commands

Infrastructure Codemods

Management Commands

Authentication

Agent Mode

fjall build

Overview

Prerequisites

Usage

Arguments

Options

Basic Usage

CI/CD Workflow

Example: GitHub Actions

Example: Buildkite

Output

Standard Output

With —output-image-url

Docker Build Targets

Troubleshooting

ECR Repository Not Found

Docker Build Failed

Authentication Failed

Next Steps

Deploy an Application

fjall deploy

​Overview

​Prerequisites

​Usage

​Arguments

​Options

​Basic Usage

​CI/CD Workflow

​Example: GitHub Actions

​Example: Buildkite

​Output

​Standard Output

​With —output-image-url

​Docker Build Targets

​Troubleshooting

​ECR Repository Not Found

​Docker Build Failed

​Authentication Failed

​Next Steps

Deploy an Application

fjall deploy

Overview

Prerequisites

Usage

Arguments

Options

Basic Usage

CI/CD Workflow

Example: GitHub Actions

Example: Buildkite

Output

Standard Output

With —output-image-url

Docker Build Targets

Troubleshooting

ECR Repository Not Found

Docker Build Failed

Authentication Failed

Next Steps