FlociClone/docs/configuration/docker-images.md

# Docker Images

Floci publishes images to [Docker Hub (`floci/floci`)](https://hub.docker.com/r/floci/floci).

Every image tag combines two independent choices: **what's inside** (variant) and **how stable it is** (channel).

## Axis 1: Variant (what's inside)

| Variant | Contents | When to use |
|---|---|---|
| **Standard** | Floci native binary only | General use: CI, local dev, Testcontainers **(recommended)** |
| **Baseline** | Floci native binary compiled for ARMv8.0 (`armv8-a`) | ARM64 hosts without LSE, including Raspberry Pi 4-class CPUs |
| **Compat** | Floci + Python 3 + AWS CLI + boto3 | Workflows that need AWS tooling available inside the container |

The compat image runs the same native binary as the standard image, so startup time and memory footprint are identical. Only the image size increases. The baseline image is different: it is an ARM64-only release artifact compiled for the ARMv8.0 ISA floor and is not published on nightly channels.

The standard image is built on Red Hat UBI 9 micro. Besides Floci it contains only bash and coreutils. There is no package manager, curl, grep or sed inside. Pick the compat image when you need tools inside the container.

## Axis 2: Channel (how stable)

| Channel | Source | Published |
|---|---|---|
| **Release** | Tagged version (e.g. `x.y.z`) | 1st and 3rd Tuesday of each month |
| **Nightly** | Tip of `main` | Every night at 23:00 CT |

Release images are stable and recommended for most use cases. Between trains, `nightly` carries every merged fix from the following morning. Nightly images track active development and may include unreleased changes.

## Full Tag Matrix

Combining both axes gives the complete set of published tags:

|  | Standard | Baseline (ARM64 only) | Compat |
|---|---|---|---|
| **Release (latest)** | `latest` ✅ | `latest-baseline` | `latest-compat` |
| **Release (pinned)** | `x.y.z` | `x.y.z-baseline` | `x.y.z-compat` |
| **Nightly (floating)** | `nightly` | — | `nightly-compat` |
| **Nightly (dated)** | `nightly-mmddyyyy` | — | `nightly-mmddyyyy-compat` |

Dated nightly tags (e.g. `nightly-05022026`) name one night's build of `main`. A same-day rerun of the nightly workflow republishes that day's tag, so for a build you can rely on not changing, pin a release version.

!!! warning
    Nightly images may include unreleased or experimental changes. Use release tags in production-like environments.

## Quick Reference

```yaml title="docker-compose.yml"
# Standard release : recommended
image: floci/floci:latest

# Compat release : includes AWS CLI and boto3
image: floci/floci:latest-compat

# ARM64 baseline release : Raspberry Pi 4 / pre-LSE AArch64 cores
image: floci/floci:latest-baseline

# Pinned release : reproducible builds
image: floci/floci:x.y.z

# Nightly : track main
image: floci/floci:nightly
```

## Multi-Architecture

Standard and compat images are published as multi-arch manifests supporting `linux/amd64` and `linux/arm64`. Baseline images are intentionally `linux/arm64` only.

## Raspberry Pi 4 and older ARM64 CPUs

If the standard ARM64 image exits with `CPU features [FP, ASIMD, CRC32, LSE] not supported`, use the `-baseline` release tag. The baseline image is compiled with GraalVM `-march=armv8-a`, so it does not require LSE. For example, use `floci/floci:latest-baseline` or pin `floci/floci:x.y.z-baseline`.

The baseline variant currently covers the Docker image only. The standalone `floci-linux-arm64` binary remains tracked in [#1114](https://github.com/floci-io/floci/issues/1114).

## Reusable Image Publishing

The `Build Floci Images` reusable workflow publishes a JVM image for an exact
branch, tag, or commit by default. This matches the ordinary Maven package and
the repository's local-development Docker image. A calling repository owns the
trigger, destination registry, credentials, and package permissions; the shared
workflow owns the multi-architecture manifest, image labels, and provenance
output.

For example, a fork can keep this small manual caller on its default branch:

```yaml title=".github/workflows/publish-images.yml"
name: Publish Floci Images

on:
  workflow_dispatch:
    inputs:
      source-ref:
        description: Floci branch, tag, or commit to publish
        required: true
        type: string
        default: main

permissions:
  contents: read
  packages: write

jobs:
  publish:
    uses: floci-io/floci/.github/workflows/build-images.yml@main
    with:
      source-ref: ${{ inputs.source-ref }}
      image: ghcr.io/${{ github.repository_owner }}/floci
```

Pin the reusable workflow to a trusted tag or full commit SHA when the caller
requires a stable build contract. The caller's `GITHUB_TOKEN` publishes a GHCR
image only below the caller's repository owner. Calls targeting another OCI
registry must pass `REGISTRY_USERNAME` and `REGISTRY_TOKEN` through the reusable
workflow's declared secrets.

The default workflow publishes a build-and-commit-derived convenience tag:

- `<YYYYMMDD.HHMMSS>.<commit-sha-8>` for the JVM image

Callers that also need native artifacts can pass `publish-native: true`. This
adds `<YYYYMMDD.HHMMSS>.<commit-sha-8>-native` and
`<YYYYMMDD.HHMMSS>.<commit-sha-8>-native-compat`; it does not change the
unqualified JVM tag. Timestamps are generated in UTC.

Each workflow invocation produces a new timestamped tag. The workflow returns
the digest-qualified JVM reference (plus native references when requested) and
uploads them in a provenance JSON artifact. Downstream tests should use a
digest-qualified reference when they require an immutable image:

```text
ghcr.io/example/floci@sha256:...
```

## What's in the Compat Image

The compat image adds the following to the standard image contents:

- Python 3 + pip
- [AWS CLI](https://pypi.org/project/awscli/) (via pip)
- [boto3](https://pypi.org/project/boto3/) (via pip)

The AWS CLI is pre-configured to talk to the local Floci endpoint, so no `--endpoint-url` flag is needed in hook scripts:

```sh
#!/bin/sh
aws sqs create-queue --queue-name my-queue   # works without --endpoint-url
aws s3 mb s3://my-bucket
```

The following environment variables are set in both the standard and compat images:

| Variable | Value |
|---|---|
| `AWS_DEFAULT_REGION` | `us-east-1` |
| `AWS_ACCESS_KEY_ID` | `test` |
| `AWS_SECRET_ACCESS_KEY` | `test` |
| `AWS_CONFIG_FILE` | `/etc/floci/aws/config` |

The compat image additionally sets:

| Variable | Value |
|---|---|
| `AWS_ENDPOINT_URL` | `http://localhost:4566` |

Override any of them at runtime via `docker run -e` or the Compose `environment` block.

## Local Development

The project ships a `docker-compose.yml` at the repository root configured for local development.
By default it uses `docker/Dockerfile`, a fast Ubuntu Noble/glibc JVM image suited for iteration
with Java 25. The release and nightly images use the native Dockerfiles described above. Switch the
`dockerfile` entry to test the native image locally:

```yaml title="docker-compose.yml"
build:
  context: .
  dockerfile: docker/Dockerfile.native   # or docker/Dockerfile for fast JVM dev build
```