Skip to content

armgit / floci

Public Imported from GitHub
0

Light, fluffy, and always free - The AWS Local Emulator alternative

chore: new docker image tag and compatibility (#691)

Hector Ventura3c98efe615ac
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 2143af3104..0802e35c29 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -14,7 +14,4 @@
/pom.xml @hectorvent
# Container build surface
-/Dockerfile @hectorvent
-/Dockerfile.jvm-package @hectorvent
-/Dockerfile.native @hectorvent
-/Dockerfile.native-package @hectorvent
+/docker/ @hectorvent
diff --git a/.github/semver.yml b/.github/semver.yml
index 9952b5670b..fd0d815ec5 100644
--- a/.github/semver.yml
+++ b/.github/semver.yml
@@ -15,13 +15,8 @@ on:
paths:
- 'src/**'
- 'pom.xml'
- - '.mvn/**'
- - 'mvnw'
- - 'mvnw.cmd'
- - 'Dockerfile'
- - 'Dockerfile.jvm-package'
- - 'Dockerfile.native'
- - 'Dockerfile.native-package'
+ - 'docker/Dockerfile.native-package'
+ - 'docker/Dockerfile.compat'
- 'docker-compose.yml'
- '.releaserc.json'
- '.github/workflows/semver.yml'
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 11459c3753..4a0077b8c6 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -7,17 +7,11 @@ on:
paths:
- 'src/**'
- 'pom.xml'
- - '.mvn/**'
- - 'mvnw'
- - 'mvnw.cmd'
- '.github/workflows/ci.yml'
pull_request:
paths:
- 'src/**'
- 'pom.xml'
- - '.mvn/**'
- - 'mvnw'
- - 'mvnw.cmd'
- '.github/workflows/ci.yml'
permissions:
diff --git a/.github/workflows/compatibility.yml b/.github/workflows/compatibility.yml
index dc0461469b..9b689c5811 100644
--- a/.github/workflows/compatibility.yml
+++ b/.github/workflows/compatibility.yml
@@ -5,14 +5,7 @@ on:
paths:
- 'src/**'
- 'pom.xml'
- - '.mvn/**'
- - 'mvnw'
- - 'mvnw.cmd'
- - 'Dockerfile'
- - 'Dockerfile.jvm-package'
- - 'Dockerfile.native'
- - 'Dockerfile.native-package'
- - 'docker-compose.yml'
+ - 'docker/Dockerfile.jvm-package'
- 'compatibility-tests/**'
- '.github/workflows/compatibility.yml'
@@ -46,7 +39,7 @@ jobs:
uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
with:
context: .
- file: Dockerfile.jvm-package
+ file: docker/Dockerfile.jvm-package
tags: floci:test
outputs: type=docker,dest=/tmp/floci-image.tar
cache-from: type=gha,scope=floci
diff --git a/.github/workflows/edge.yml b/.github/workflows/edge.yml
deleted file mode 100644
index d46471a3e7..0000000000
--- a/.github/workflows/edge.yml
+++ /dev/null
@@ -1,61 +0,0 @@
-name: Edge
-
-# Builds and publishes the JVM image from the tip of main as the `edge` Docker tag.
-# Runs on a weekly schedule (every Monday 00:00 UTC) and can be triggered manually.
-# Uses JVM-only build to keep runtime cost low (~2-3 min vs ~15 min for native).
-#
-# Published tag: floci/floci:edge
-#
-# Required secrets: DOCKERHUB_USERNAME, DOCKERHUB_TOKEN
-
-on:
- schedule:
- - cron: '0 0 * * 1' # Every Monday at 00:00 UTC
- workflow_dispatch: # Allow maintainers to trigger manually
-
-permissions:
- contents: read
-
-concurrency:
- group: ${{ github.workflow }}-${{ github.ref }}
- cancel-in-progress: true
-
-jobs:
- build-and-push-edge:
- name: Build and push edge image
- runs-on: ubuntu-latest
- timeout-minutes: 30
-
- steps:
- - uses: actions/checkout@v6
- with:
- ref: main
-
- - uses: actions/setup-java@v5
- with:
- java-version: '25'
- distribution: 'temurin'
- cache: maven
-
- - name: Build JVM artifact
- run: mvn clean package -DskipTests -q
-
- - uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
-
- - uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
- with:
- username: ${{ secrets.DOCKERHUB_USERNAME }}
- password: ${{ secrets.DOCKERHUB_TOKEN }}
-
- - name: Build and push edge image
- uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
- with:
- context: .
- file: Dockerfile.jvm-package
- platforms: linux/amd64,linux/arm64
- push: true
- tags: floci/floci:edge
- cache-from: type=gha
- cache-to: type=gha,mode=max
- build-args: |
- INSTALL_AWS_CLI=true
diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
new file mode 100644
index 0000000000..ae482330e9
--- /dev/null
+++ b/.github/workflows/nightly.yml
@@ -0,0 +1,166 @@
+name: Nightly
+
+# Builds and publishes native images from the tip of main as nightly Docker tags.
+# Runs every night at 22:00 CT (03:00 UTC, approximate — shifts 1 h in CST winter).
+# Can also be triggered manually.
+#
+# Published tags:
+# Native: floci/floci:nightly floci/floci:nightly-mmddyyyy
+# Compat: floci/floci:nightly-compat floci/floci:nightly-mmddyyyy-compat
+#
+# Required secrets: DOCKERHUB_USERNAME, DOCKERHUB_TOKEN
+
+on:
+ schedule:
+ - cron: '0 4 * * *' # 23:00 CT (CDT/UTC-5); shifts to 23:00 CST in winter
+ workflow_dispatch: # Allow maintainers to trigger manually
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ # ── Compute nightly version (CT date) ────────────────────────────────────
+ prepare:
+ name: Prepare nightly version
+ runs-on: ubuntu-latest
+ outputs:
+ version: ${{ needs.prepare.outputs.version }}
+
+ steps:
+ - name: Set date version (CT)
+ id: date
+ run: echo "version=$(TZ='America/Chicago' date +'%m%d%Y')" >> "$GITHUB_OUTPUT"
+
+ # ── Build native artifact — amd64 ────────────────────────────────────────
+ build-native-amd64:
+ name: Build native artifact (amd64)
+ needs: prepare
+ runs-on: ubuntu-latest
+ timeout-minutes: 45
+
+ steps:
+ - uses: actions/checkout@v6
+ with:
+ ref: main
+
+ - uses: graalvm/setup-graalvm@60c26726de13f8b90771df4bc1641a52a3159994 # v1
+ with:
+ java-version: '24'
+ distribution: 'mandrel'
+ cache: maven
+ github-token: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Set nightly version
+ run: mvn versions:set -DnewVersion="nightly-${{ needs.prepare.outputs.version }}" -DgenerateBackupPoms=false -q
+
+ - name: Build native executable
+ run: mvn clean package -Dnative -DskipTests -B -Dquarkus.native.additional-build-args-append="-march=x86-64-v2"
+
+ - uses: actions/upload-artifact@v7
+ with:
+ name: native-amd64
+ path: |
+ target/*-runner
+ target/*.properties
+ target/*.so
+ if-no-files-found: warn
+ retention-days: 1
+
+ # ── Build native artifact — arm64 ────────────────────────────────────────
+ build-native-arm64:
+ name: Build native artifact (arm64)
+ needs: prepare
+ runs-on: ubuntu-24.04-arm
+ timeout-minutes: 45
+
+ steps:
+ - uses: actions/checkout@v6
+ with:
+ ref: main
+
+ - uses: graalvm/setup-graalvm@60c26726de13f8b90771df4bc1641a52a3159994 # v1
+ with:
+ java-version: '24'
+ distribution: 'mandrel'
+ cache: maven
+ github-token: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Set nightly version
+ run: mvn versions:set -DnewVersion="nightly-${{ needs.prepare.outputs.version }}" -DgenerateBackupPoms=false -q
+
+ - name: Build native executable
+ run: mvn clean package -Dnative -DskipTests -B
+
+ - uses: actions/upload-artifact@v7
+ with:
+ name: native-arm64
+ path: |
+ target/*-runner
+ target/*.properties
+ target/*.so
+ if-no-files-found: warn
+ retention-days: 1
+
+ # ── Push native + compat Docker images ───────────────────────────────────
+ push-native:
+ name: Push native and compat Docker images
+ needs: [prepare, build-native-amd64, build-native-arm64]
+ runs-on: ubuntu-latest
+ timeout-minutes: 30
+
+ steps:
+ - uses: actions/checkout@v6
+ with:
+ ref: main
+
+ - uses: actions/download-artifact@v8
+ with:
+ name: native-amd64
+ path: native/amd64/
+
+ - uses: actions/download-artifact@v8
+ with:
+ name: native-arm64
+ path: native/arm64/
+
+ - name: Make binaries executable
+ run: chmod +x native/amd64/*-runner native/arm64/*-runner
+
+ - uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+
+ - uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+ with:
+ username: ${{ secrets.DOCKERHUB_USERNAME }}
+ password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+ - name: Build and push native nightly image
+ uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+ with:
+ context: .
+ file: docker/Dockerfile.native-package
+ platforms: linux/amd64,linux/arm64
+ push: true
+ tags: |
+ floci/floci:nightly
+ floci/floci:nightly-${{ needs.prepare.outputs.version }}
+ cache-from: type=gha
+ cache-to: type=gha,mode=max
+
+ - name: Build and push compat nightly image
+ uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+ with:
+ context: .
+ file: docker/Dockerfile.compat
+ platforms: linux/amd64,linux/arm64
+ push: true
+ tags: |
+ floci/floci:nightly-compat
+ floci/floci:nightly-${{ needs.prepare.outputs.version }}-compat
+ build-args: |
+ VERSION=nightly-${{ needs.prepare.outputs.version }}
+ cache-from: type=gha
+ cache-to: type=gha,mode=max
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index b66b611f99..a33c79615e 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,11 +1,11 @@
name: Release
# Triggered when a version tag (e.g. 1.2.3) is pushed.
-# Builds native (amd64 + arm64) and JVM Docker images and pushes them to Docker Hub.
+# Builds native (amd64 + arm64) Docker images and pushes them to Docker Hub.
#
# Published tags:
-# Native: floci/floci:1.2.3 floci/floci:latest
-# JVM: floci/floci:1.2.3-jvm floci/floci:latest-jvm
+# Native: floci/floci:1.2.3 floci/floci:latest
+# Compat: floci/floci:1.2.3-compat floci/floci:latest-compat
#
# Required secrets: DOCKERHUB_USERNAME, DOCKERHUB_TOKEN
@@ -26,30 +26,6 @@ concurrency:
cancel-in-progress: true
jobs:
- # ── Build JVM artifact ────────────────────────────────────────────────────
- build-jvm:
- name: Build JVM artifact
- runs-on: ubuntu-latest
- timeout-minutes: 20
-
- steps:
- - uses: actions/checkout@v6
-
- - uses: actions/setup-java@v5
- with:
- java-version: '25'
- distribution: 'temurin'
- cache: maven
-
- - name: Build JVM artifact
- run: mvn clean package -DskipTests -q
-
- - uses: actions/upload-artifact@v7
- with:
- name: jvm-artifact
- path: target/quarkus-app/
- retention-days: 1
-
# ── Build native artifact — amd64 ────────────────────────────────────────
build-native-amd64:
name: Build native artifact (amd64)
@@ -108,53 +84,9 @@ jobs:
if-no-files-found: warn
retention-days: 1
- # ── Push JVM Docker image ─────────────────────────────────────────────────
- push-jvm:
- name: Push JVM Docker image
- needs: build-jvm
- runs-on: ubuntu-latest
- timeout-minutes: 30
-
- steps:
- - uses: actions/checkout@v6
-
- - name: Extract version
- id: version
- run: echo "version=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
-
- - uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
-
- - uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
- with:
- username: ${{ secrets.DOCKERHUB_USERNAME }}
- password: ${{ secrets.DOCKERHUB_TOKEN }}
-
- - uses: actions/download-artifact@v8
- with:
- name: jvm-artifact
- path: target/quarkus-app/
-
- - name: Build and push JVM image
- uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
- with:
- context: .
- file: Dockerfile.jvm-package
- platforms: linux/amd64,linux/arm64
- push: true
- tags: |
- floci/floci:${{ steps.version.outputs.version }}-jvm
- floci/floci:latest-jvm
- floci/floci:${{ steps.version.outputs.version }}-aws
- floci/floci:latest-aws
- cache-from: type=gha
- cache-to: type=gha,mode=max
- build-args: |
- VERSION=${{ steps.version.outputs.version }}
- INSTALL_AWS_CLI=true
-
- # ── Push native Docker images (multi-arch manifest) ───────────────────────
+ # ── Push native + compat Docker images ───────────────────────────────────
push-native:
- name: Push native Docker images
+ name: Push native and compat Docker images
needs: [build-native-amd64, build-native-arm64]
runs-on: ubuntu-latest
timeout-minutes: 30
@@ -190,7 +122,7 @@ jobs:
uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
with:
context: .
- file: Dockerfile.native-package
+ file: docker/Dockerfile.native-package
platforms: linux/amd64,linux/arm64
push: true
tags: |
@@ -199,4 +131,19 @@ jobs:
build-args: |
VERSION=${{ steps.version.outputs.version }}
cache-from: type=gha
- cache-to: type=gha,mode=max
\ No newline at end of file
+ cache-to: type=gha,mode=max
+
+ - name: Build and push compat multi-arch image
+ uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+ with:
+ context: .
+ file: docker/Dockerfile.compat
+ platforms: linux/amd64,linux/arm64
+ push: true
+ tags: |
+ floci/floci:${{ steps.version.outputs.version }}-compat
+ floci/floci:latest-compat
+ build-args: |
+ VERSION=${{ steps.version.outputs.version }}
+ cache-from: type=gha
+ cache-to: type=gha,mode=max
diff --git a/README.md b/README.md
index 5c8c9f1376..7815adcf42 100644
--- a/README.md
+++ b/README.md
@@ -708,11 +708,33 @@ Available compatibility test modules:
## Image Tags
-| Tag | Description |
-|---|---|
-| `latest` | Native image — sub-second startup **(recommended)** |
-| `latest-jvm` | JVM image |
-| `x.y.z` / `x.y.z-jvm` | Pinned releases |
+Every tag combines two choices: **variant** (what's inside) and **channel** (how stable).
+
+| | Standard | Compat (+ AWS CLI + boto3) |
+|---|---|---|
+| **Release (latest)** | `latest` ✅ | `latest-compat` |
+| **Release (pinned)** | `x.y.z` | `x.y.z-compat` |
+| **Nightly (floating)** | `nightly` | `nightly-compat` |
+| **Nightly (dated)** | `nightly-mmddyyyy` | `nightly-mmddyyyy-compat` |
+
+- **Standard** — GraalVM native binary. ~24 ms startup, ~40 MB image, ~13 MiB idle memory.
+- **Compat** — Extends the standard image with Python 3, AWS CLI, and boto3. Same startup and memory, larger image.
+- **Release** — Published on every stable version tag.
+- **Nightly** — Built every night at 22:00 CT from `main`. Dated tags (e.g. `nightly-05022026`) are fixed; `nightly` always points to the latest.
+
+```yaml
+# Recommended
+image: floci/floci:latest
+
+# With AWS CLI + boto3
+image: floci/floci:latest-compat
+
+# Pinned
+image: floci/floci:1.5.11
+
+# Track main
+image: floci/floci:nightly
+```
## Configuration
diff --git a/docker-compose.yml b/docker-compose.yml
index 7d9a20f78d..bdfe7e4d24 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -2,7 +2,7 @@ services:
floci:
build:
context: .
- dockerfile: Dockerfile.native
+ dockerfile: docker/Dockerfile
ports:
- "4566:4566"
- "6379-6399:6379-6399"
diff --git a/Dockerfile b/docker/Dockerfile
similarity index 99%
rename from Dockerfile
rename to docker/Dockerfile
index e0e2a82585..d4c9d89895 100644
--- a/Dockerfile
+++ b/docker/Dockerfile
@@ -12,6 +12,11 @@ RUN mvn clean package -DskipTests -q
# Stage 2: Runtime
FROM eclipse-temurin:25-jre-alpine
+
+ARG VERSION=latest
+ENV FLOCI_VERSION=${VERSION}
+ENV FLOCI_STORAGE_PERSISTENT_PATH=/app/data
+
WORKDIR /app
COPY --from=build /build/target/quarkus-app/ quarkus-app/
@@ -24,8 +29,4 @@ EXPOSE 4566 6379-6399
HEALTHCHECK --interval=5s --timeout=3s --retries=5 \
CMD wget -q --spider http://localhost:4566/_floci/health || exit 1
-ARG VERSION=latest
-ENV FLOCI_VERSION=${VERSION}
-ENV FLOCI_STORAGE_PERSISTENT_PATH=/app/data
-
ENTRYPOINT ["java", "--enable-native-access=ALL-UNNAMED", "-jar", "quarkus-app/quarkus-run.jar"]
diff --git a/docker/Dockerfile.compat b/docker/Dockerfile.compat
new file mode 100644
index 0000000000..f9d7af44c0
--- /dev/null
+++ b/docker/Dockerfile.compat
@@ -0,0 +1,10 @@
+FROM floci/floci:${VERSION}
+ARG VERSION=latest
+
+USER root
+RUN microdnf install -y --nodocs python3 python3-pip \
+ && pip3 install --no-cache-dir awscli boto3 \
+ && microdnf clean all \
+ && rm -rf /root/.cache/pip
+
+USER 1001
diff --git a/Dockerfile.jvm-package b/docker/Dockerfile.jvm-package
similarity index 93%
rename from Dockerfile.jvm-package
rename to docker/Dockerfile.jvm-package
index 8d808e623c..638b75ab60 100644
--- a/Dockerfile.jvm-package
+++ b/docker/Dockerfile.jvm-package
@@ -36,11 +36,9 @@ RUN mkdir -p /app/data \
VOLUME /app/data
+COPY --chmod=755 docker/entrypoint.sh /usr/local/bin/docker-entrypoint.sh
COPY --chown=1001:root target/quarkus-app quarkus-app/
-COPY docker/entrypoint.sh /usr/local/bin/docker-entrypoint.sh
-RUN chmod +x /usr/local/bin/docker-entrypoint.sh
-
EXPOSE 4566 6379-6399
HEALTHCHECK --interval=5s --timeout=3s --retries=5 \
diff --git a/Dockerfile.native b/docker/Dockerfile.native
similarity index 95%
rename from Dockerfile.native
rename to docker/Dockerfile.native
index 4d9831fd20..e3f394af55 100644
--- a/Dockerfile.native
+++ b/docker/Dockerfile.native
@@ -64,11 +64,9 @@ ENV FLOCI_VERSION=${VERSION}
ENV FLOCI_STORAGE_PERSISTENT_PATH=/app/data
COPY --from=build /app/target/*-runner /app/application
+COPY --chmod=755 docker/entrypoint.sh /usr/local/bin/docker-entrypoint.sh
RUN chmod +x /app/application
-COPY docker/entrypoint.sh /usr/local/bin/docker-entrypoint.sh
-RUN chmod +x /usr/local/bin/docker-entrypoint.sh
-
ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]
CMD ["/app/application"]
diff --git a/Dockerfile.native-package b/docker/Dockerfile.native-package
similarity index 93%
rename from Dockerfile.native-package
rename to docker/Dockerfile.native-package
index f66e91f7ec..2ef4794e75 100644
--- a/Dockerfile.native-package
+++ b/docker/Dockerfile.native-package
@@ -37,8 +37,7 @@ VOLUME /app/data
COPY --chown=1001:root native/${TARGETARCH}/ /app/
RUN mv /app/*-runner /app/application && chmod +x /app/application
-COPY docker/entrypoint.sh /usr/local/bin/docker-entrypoint.sh
-RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+COPY --chmod=755 docker/entrypoint.sh /usr/local/bin/docker-entrypoint.sh
EXPOSE 4566
diff --git a/run-docker-tests.sh b/docker/run-docker-tests.sh
similarity index 98%
rename from run-docker-tests.sh
rename to docker/run-docker-tests.sh
index 484b53c679..9fcb66ac1d 100644
--- a/run-docker-tests.sh
+++ b/docker/run-docker-tests.sh
@@ -32,7 +32,6 @@ SUITES=(
"sdk-test-java"
"sdk-test-go"
"sdk-test-awscli"
- "sdk-test-rust"
"compat-cdk"
"compat-terraform"
"compat-opentofu"
diff --git a/docs/configuration/docker-images.md b/docs/configuration/docker-images.md
new file mode 100644
index 0000000000..ca7a69afac
--- /dev/null
+++ b/docs/configuration/docker-images.md
@@ -0,0 +1,77 @@
+# 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)** |
+| **Compat** | Floci + Python 3 + AWS CLI + boto3 | Workflows that need AWS tooling available inside the container |
+
+The compat image is built on top of the standard image — startup time and memory footprint are identical. Only the image size increases.
+
+## Axis 2 — Channel (how stable)
+
+| Channel | Source | Published |
+|---|---|---|
+| **Release** | Tagged version (e.g. `1.5.11`) | On every release |
+| **Nightly** | Tip of `main` | Every night at 22:00 CT |
+
+Release images are stable and recommended for most use cases. Nightly images track active development and may include unreleased changes.
+
+## Full Tag Matrix
+
+Combining both axes gives the complete set of published tags:
+
+| | Standard | Compat |
+|---|---|---|
+| **Release (latest)** | `latest` ✅ | `latest-compat` |
+| **Release (pinned)** | `x.y.z` | `x.y.z-compat` |
+| **Nightly (floating)** | `nightly` | `nightly-compat` |
+| **Nightly (dated)** | `nightly-mmddyyyy` | `nightly-mmddyyyy-compat` |
+
+Dated nightly tags (e.g. `nightly-05022026`) are fixed and never move — use them for reproducible builds from `main`.
+
+!!! 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
+
+# Pinned release — reproducible builds
+image: floci/floci:1.5.11
+
+# Nightly — track main
+image: floci/floci:nightly
+```
+
+## Multi-Architecture
+
+All images are published as multi-arch manifests supporting `linux/amd64` and `linux/arm64`. Docker selects the correct variant automatically.
+
+## What's in the Compat Image
+
+The compat image installs the following on top of the standard image:
+
+- Python 3 + pip (via `microdnf` on `ubi9-minimal`)
+- [AWS CLI](https://pypi.org/project/awscli/) (via pip)
+- [boto3](https://pypi.org/project/boto3/) (via pip)
+
+## 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 JVM build suited for iteration). 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
+```
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index ae01d4b5f3..3e90ec3f10 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -10,46 +10,46 @@ No installation required beyond Docker itself.
docker pull floci/floci:latest
```
-| Tag | Description |
-|---|---|
-| `latest` | Native image — sub-second startup, low memory (**default**) |
-| `x.y.z` | Native image — specific release version |
-| `latest-jvm` | JVM image — most compatible |
-| `x.y.z-jvm` | JVM image — specific release version |
-
### Requirements
- Docker 20.10+
- `docker compose` v2+ (plugin syntax, not standalone `docker-compose`)
-## Native vs JVM
+## Image Tags
+
+Each tag combines a **variant** (what's inside) and a **channel** (how stable).
+
+| | Standard | Compat (+ AWS CLI + boto3) |
+|---|---|---|
+| **Release (latest)** | `latest` ✅ | `latest-compat` |
+| **Release (pinned)** | `x.y.z` | `x.y.z-compat` |
+| **Nightly (floating)** | `nightly` | `nightly-compat` |
+| **Nightly (dated)** | `nightly-mmddyyyy` | `nightly-mmddyyyy-compat` |
-The `latest` tag is the native image — a self-contained executable with no JVM dependency.
+For the full breakdown see [Docker Images](../configuration/docker-images.md).
+
+## Choosing a tag
```yaml title="docker-compose.yml"
+# Standard release — recommended for most use cases
services:
floci:
- image: floci/floci:latest # native — recommended
+ image: floci/floci:latest
ports:
- "4566:4566"
```
-Use the JVM image if you need broader platform compatibility or encounter native image issues:
+Use the compat image if your workflow requires the AWS CLI or boto3 available inside the container:
```yaml title="docker-compose.yml"
services:
floci:
- image: floci/floci:latest-jvm
+ image: floci/floci:latest-compat
ports:
- "4566:4566"
```
-### Startup comparison
-
-| Image | Tag | Typical startup | Idle memory |
-|---|---|---|---|
-| Native | `latest` / `x.y.z` | ~24 ms | ~13 MiB |
-| JVM | `latest-jvm` / `x.y.z-jvm` | ~2 s | ~250 MB |
+Both variants have identical startup time (~24 ms) and memory footprint (~13 MiB).
## Build from Source
diff --git a/mkdocs.yml b/mkdocs.yml
index 05332d5c1c..c21c5efee0 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -60,6 +60,7 @@ nav:
- Installation: getting-started/installation.md
- AWS CLI & SDK Setup: getting-started/aws-setup.md
- Configuration:
+ - Docker Images: configuration/docker-images.md
- Docker Compose: configuration/docker-compose.md
- Ports Reference: configuration/ports.md
- application.yml Reference: configuration/application-yml.md