second first commit

2026-09-22 08:57:00 -04:00
parent e88d7e2ff3
commit 0aef7fb2d8
4766 changed files with 1236986 additions and 0 deletions
@@ -0,0 +1,176 @@
+# 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
+```