> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fjall.io/llms.txt
> Use this file to discover all available pages before exploring further.

# fjall build

> Build and push your Fjall application's Docker image to AWS ECR for the next deployment.

## 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

```bash theme={null}
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:

```bash theme={null}
fjall build api
```

Build a specific service:

```bash theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
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:

```dockerfile theme={null}
FROM node:22 AS base
# ...

FROM base AS development
# ...

FROM base AS production
# ...
```

Build a specific target:

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
docker build -t test .
```

### Authentication Failed

```
Error: Failed to get AWS account ID
```

**Cause:** invalid or expired AWS credentials.

**Solution:** re-authenticate.

```bash theme={null}
fjall login
# or
aws sso login
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Deploy an Application" icon="rocket" href="/deployment/deploy-application">
    Deploy your built image to AWS
  </Card>

  <Card title="fjall deploy" icon="cloud-arrow-up" href="/cli/deploy">
    Full reference for the deploy command
  </Card>
</CardGroup>