Skip to main content

​
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

RequirementWhy
Infrastructure deployedRun fjall deploy <app> at least once to create the ECR repository
Docker runningThe Docker daemon must be running locally
AWS credentialsValid AWS credentials with ECR access

​
Usage

fjall build <app> [service] [options]

​
Arguments

ArgumentDescriptionRequired
appApplication nameYes
serviceSpecific service to buildNo

​
Options

OptionDescriptionExample
--target <target>Docker build target stage--target production
--output-image-urlPrint the image URL for CI capture--output-image-url
-v, --verboseShow detailed output-v
--non-interactiveForce 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:
  1. Build and push images.
  2. Run tests against the built image.
  3. Deploy with the pre-built image.

​
Example: GitHub Actions

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

      - name: Build and push
        id: build
        run: |
          fjall build api --output-image-url --non-interactive
          # Captures IMAGE_URL from 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 --deploy-only --skip-build --non-interactive

​
Example: Buildkite

steps:
  - label: "Build"
    command: |
      fjall build api --output-image-url --non-interactive

  - label: "Test"
    depends_on: "build"
    command: |
      docker run ${IMAGE_URL} npm test

  - label: "Deploy"
    depends_on: "test"
    command: |
      fjall deploy api --deploy-only --skip-build --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:abc123

Next steps:
  Run tests: docker run 123456789.dkr.ecr.ap-southeast-2.amazonaws.com/api-ecr:abc123 npm test
  Deploy: fjall deploy api --deploy-only --skip-build

​
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:abc123
ALL_IMAGE_URLS=123456789.dkr.ecr.ap-southeast-2.amazonaws.com/api-ecr:abc123
============================================================
IMAGE_URL contains the last built image. ALL_IMAGE_URLS contains a comma-separated list of all images when building multiple services.

​
Docker Build Targets

If your Dockerfile uses multi-stage builds with named targets: 
FROM node:22 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

​
Next Steps

Deploy an Application

Deploy your built image to AWS

fjall deploy

Full reference for the deploy command