Console Login

Building Floci from source on Ubuntu 24.04 with JDK 25

The problem

Floci is a local AWS emulator: you point the AWS CLI or an SDK at http://localhost:4566 and get S3, DynamoDB, SQS and many more services without an AWS account. The repository is MIT licensed, and the task that selected it reported that the latest push-triggered "CI" workflow run on main concluded success. The quick start suggests a CLI or a Docker image. I wanted the other route, building it from source on a plain machine.

The machine is a clean container. I ran uname -a and cat /etc/os-release and it reports Ubuntu 24.04.5 LTS on a 6.18 kernel. It has OpenJDK 21 and Maven 3.9.11 preinstalled, and it has a Docker client but no Docker daemon. It hit three separate walls before the first request worked.

uname -a
Linux vm 6.18.44-fc-v726 #1 SMP PREEMPT_DYNAMIC @0 x86_64 x86_64 x86_64 GNU/Linux
cat /etc/os-release | head -2
PRETTY_NAME="Ubuntu 24.04.5 LTS"
NAME="Ubuntu"

Wall one: the JDK is too old

I cloned the repository with git clone --depth 1 (commit e8f1691, Floci 2.5.0 in pom.xml) and followed the documented source build, mvn clean package -DskipTests. On the preinstalled JDK 21 the build stops before compiling anything, with an error that names the fix.

export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
mvn -B -q clean package -DskipTests 2>&1 | grep -v "^\[ERROR\] *$" | head -4
Picked up JAVA_TOOL_OPTIONS: -XX:+IgnoreUnrecognizedVMOptions -XX:-UseBASE64Intrinsics
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-enforcer-plugin:3.6.3:enforce (enforce-java) on project floci: 
[ERROR] Rule 0: org.apache.maven.enforcer.rules.version.RequireJavaVersion failed with message:
[ERROR] Floci requires JDK 25. Set JAVA_HOME to JDK 25.

The cause

The first wall is deliberate. The pom.xml declares a Maven Enforcer rule, and I printed the lines around the message to see how strict it is. The version range is [25,26), so JDK 25 is required: not "25 or newer" and not 21. Ubuntu 24.04 ships JDK 21 as its default, and apt-cache policy openjdk-25-jdk-headless printed nothing here (I did not run apt update), so a JDK 25 has to come from somewhere else.

grep -n "Floci requires JDK" -B8 pom.xml | head -20
920-                                    <version>[25,26)</version>
921:                                    <message>Floci requires JDK 25. Set JAVA_HOME to JDK 25.</message>

The second wall appeared only after I fixed the first, and it is the less obvious one. A JDK tarball carries its own trust store. The sandbox routes HTTPS through an egress gateway that re-signs certificates with its own CA. The Ubuntu JDK reads the system trust store, where that CA is installed, but the freshly unpacked JDK 25 has the stock Temurin list, which does not contain it. Maven then cannot download a single plugin.

The third wall is that there is no Docker daemon. I confirmed it with docker info, whose last line says it cannot connect to /var/run/docker.sock. That does not stop the build, but it limits what the running emulator can do, because container-backed services such as RDS or Lambda have nothing to start containers with.

docker info 2>&1 | tail -1
failed to connect to the docker API at unix:///var/run/docker.sock; check if the path is correct and if the daemon is running: dial unix /var/run/docker.sock: connect: no such file or directory

Source of truth

Three documents decide what is correct here. The repository's own installation guide has a "Build from Source" section. It lists Java 25+ and Maven 3.9+ as prerequisites, and gives mvn clean package -DskipTests followed by java -jar target/quarkus-app/quarkus-run.jar. It also says Docker is optional: without it, services that need containers keep their control plane but start none.

The pom.xml is the stricter authority, because it is what actually fails the build, and it pins the range to exactly JDK 25. For the TLS problem, the Maven guide on repository SSL and the JDK's standard javax.net.ssl.trustStore properties are the reference: any JVM, including the one running Maven, can be told which trust store to use. For the client side, the AWS CLI endpoint documentation describes the AWS_ENDPOINT_URL variable the Floci README relies on.

Ways to fix it

Get a JDK 25

There are several ways. A tarball from the Adoptium API needs no package manager and can sit in /opt beside the system JDK. SDKMAN, which the repository's CONTRIBUTING file suggests, does the same thing per user. A distribution package is the cleanest where one exists, but I did not get a package candidate on this Ubuntu release, so I did not rely on it.

Fix the trust store

Either point Maven at the system trust store through MAVEN_OPTS, or import the gateway CA into the new JDK's cacerts. The first changes nothing on disk. The second is permanent for that JDK but means modifying a file inside the JDK directory.

Skip the build

The installation guide also offers prebuilt native binaries and a Docker image. The image is out here, because there is no Docker daemon. I did not try the native binary, because I wanted to build from source, run the tests and see what the build needs on a stock machine.

Why this fix

I chose the Temurin tarball in /opt/jdk25 plus a MAVEN_OPTS trust store override. The tarball is reversible by deleting one directory and leaves the system JDK 21 untouched, which matters on a shared box where other tools expect 21. The override is a per-shell setting rather than an edit to the JDK. It reuses the trust store the operating system already maintains, so no certificate is copied or hand-managed.

The trade-off is that both settings live in my shell environment, so a new shell forgets them. A short wrapper script, or a shell profile entry, would make them permanent on a developer machine. I kept environment variables so that every step in the article stays visible and easy to undo.

Fixing it step by step

Install JDK 25

I downloaded the latest JDK 25 build from the Adoptium API and unpacked it into /opt/jdk25. The API answered with a redirect to a GitHub release asset, and curl -L followed it. The chain ends by printing the version of the new JDK, so the same line installs it and proves it starts.

cd /tmp; curl -fsSL -o jdk25.tgz "https://api.adoptium.net/v3/binary/latest/25/ga/linux/x64/jdk/hotspot/normal/eclipse" && ls -la jdk25.tgz && mkdir -p /opt/jdk25 && tar xzf jdk25.tgz -C /opt/jdk25 --strip-components=1 && /opt/jdk25/bin/java -version 2>&1
-rw-r--r-- 1 root root 141362230 Nov 20 10:21 jdk25.tgz
openjdk version "25.0.5.1" 2026-11-17 LTS
OpenJDK Runtime Environment Temurin-25.0.5.1+2 (build 25.0.5.1+2-LTS)
OpenJDK 64-Bit Server VM Temurin-25.0.5.1+2 (build 25.0.5.1+2-LTS, mixed mode, sharing)

Hit the trust store error

With JAVA_HOME=/opt/jdk25 the enforcer rule passes, and then the very next plugin download fails. A normal run only says that plugin dependencies "could not be resolved", with a list of artifact descriptors that failed to read. A debug run with -X shows the real reason, which is a TLS validation failure. I unset MAVEN_OPTS first so that this run used the JDK's own trust store.

export JAVA_HOME=/opt/jdk25
mvn -B -X validate resources:resources 2>&1 | grep -m1 -o "(certificate_unknown) PKIX path building failed"
(certificate_unknown) PKIX path building failed

The same host is reachable with curl, so the network is fine. Asking curl for the certificate issuer shows why the JDK disagrees, and comparing the two cacerts files shows the system JDK uses the operating system store through a symlink while the tarball ships its own file.

curl -sv https://repo.maven.apache.org 2>&1 | grep -o "CN=Egress Gateway[^;]*"
CN=Egress Gateway SDS Issuing CA (production)
ls -la /opt/jdk25/lib/security/cacerts /usr/lib/jvm/java-21-openjdk-amd64/lib/security/cacerts
-rw-r--r-- 1 root root 152820 Nov 17 23:33 /opt/jdk25/lib/security/cacerts
lrwxrwxrwx 1 root root     27 Oct 29 14:31 /usr/lib/jvm/java-21-openjdk-amd64/lib/security/cacerts -> /etc/ssl/certs/java/cacerts

The practical lesson is that the system JDK and the tarball JDK trust different certificate authorities. If you are behind a corporate TLS-inspecting proxy, you will most likely see the same error for the same reason, and the fix below applies there too.

Build with the system trust store

export MAVEN_OPTS="-Djavax.net.ssl.trustStore=/etc/ssl/certs/java/cacerts -Djavax.net.ssl.trustStorePassword=changeit"
cd /tmp/floci; time mvn -B -q clean package -DskipTests > /tmp/build2.log 2>&1; ls target/quarkus-app
app
lib
quarkus
quarkus-app-dependencies.txt
quarkus-run.jar


real	1m58.241s

This is the second build, with the local Maven cache already filled. It is a single measurement on this machine, not a benchmark. The build produced the quarkus-app directory with quarkus-run.jar, the entry point the installation guide tells you to start with java -jar.

Start the service

cd /tmp/floci; nohup java -jar target/quarkus-app/quarkus-run.jar > /tmp/floci2.log 2>&1 &
grep -m1 "started in" /tmp/floci2.log
2026-11-20 10:32:27,301 INFO  [io.quarkus] floci 2.5.0 on JVM (powered by Quarkus 3.40.1.1) started in 3.938s. Listening on: http://127.0.0.1:4566

Floci logged warnings about the missing daemon. I counted them and printed the start of each line. The first one, from DockerAvailabilityReport, names the services that run no containers without a daemon. The other four are about leftover containers it could not list. Everything that does not need a container is unaffected, so I tested S3, DynamoDB and SQS.

grep -c "WARN" /tmp/floci2.log; grep "WARN" /tmp/floci2.log | cut -c1-110 | head -5
5
2026-11-20 10:32:26,523 WARN  [io.flo.aws.lif.DockerAvailabilityReport] Docker is not reachable at unix:///var
2026-11-20 10:32:26,902 WARN  [io.flo.aws.ser.ecs.con.EcsContainerManager] Could not list leftover containers 
2026-11-20 10:32:27,207 WARN  [io.flo.aws.ser.lam.lau.LambdaContainerReconciler] Could not list leftover conta
2026-11-20 10:32:27,268 WARN  [io.flo.aws.ser.ec2.net.VpcNetworkManager] Could not reconcile orphaned VPC netw
2026-11-20 10:32:27,271 WARN  [io.flo.aws.ser.ec2.Ec2ContainerManager] Could not reconcile orphaned EC2 contai
curl -s localhost:4566/_floci/health | head -c 120; echo
{"status":"UP","cloud":"aws","services":{"ssm":"running","sqs":"running","s3":"running","dynamodb":"running","sns":"runn

Verify with real requests

The sandbox had no AWS CLI, so I created a virtual environment with python3 -m venv awsenv in /tmp and installed AWS CLI v1 from PyPI into it. Re-running the install now just confirms what is there. I then set the environment variables from the README, with dummy credentials, and used S3 first: create a bucket, upload a 17-byte file, read it back.

/tmp/awsenv/bin/pip install awscli 2>&1 | grep -i "already satisfied: awscli\|Successfully" | cut -c1-120
Requirement already satisfied: awscli in ./awsenv/lib/python3.11/site-packages (1.46.3)
/tmp/awsenv/bin/aws --version
aws-cli/1.46.3 Python/3.11.18 Linux/6.18.44-fc-v726 botocore/1.43.62
export PATH=/tmp/awsenv/bin:$PATH AWS_ENDPOINT_URL=http://localhost:4566 AWS_DEFAULT_REGION=us-east-1 AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test; aws s3 mb s3://my-bucket
make_bucket: my-bucket
aws s3 cp /tmp/hello.txt s3://my-bucket/hello.txt
aws s3 cp s3://my-bucket/hello.txt -
hello from floci

S3 worked straight away. DynamoDB also worked: I created a table, put one item with a string key and a numeric attribute, and read that attribute back by filtering the output with a query expression. Both calls ran against the local endpoint.

aws dynamodb create-table --table-name demo-table --attribute-definitions AttributeName=pk,AttributeType=S --key-schema AttributeName=pk,KeyType=HASH --billing-mode PAY_PER_REQUEST --query TableDescription.TableStatus
"ACTIVE"
aws dynamodb put-item --table-name demo-table --item '{"pk":{"S":"a"},"v":{"N":"1"}}'
aws dynamodb get-item --table-name demo-table --key '{"pk":{"S":"a"}}' --query Item.v.N
"1"

Then SQS failed, with an error I had not expected from a local emulator, since the same variables and credentials had just worked for S3 and DynamoDB. Only SQS failed, so the difference had to be in how that one request was built.

aws sqs create-queue --queue-name q1
An error occurred (InvalidClientTokenId) when calling the CreateQueue operation: The security token included in the request is invalid.

A client-side catch: AWS CLI v1 and SQS

That error is the message real AWS sends for bad credentials, so I suspected the request never reached Floci. The CLI debug log prints the endpoint it resolved. For DynamoDB it was the local address, and for SQS it was the public AWS hostname.

aws sqs create-queue --queue-name q1 --debug 2>&1 | grep -m1 -o "Endpoint provider result: .*"
Endpoint provider result: https://queue.amazonaws.com
aws dynamodb list-tables --debug 2>&1 | grep -m1 -o "Endpoint provider result: .*"
Endpoint provider result: http://localhost:4566

The cause is in the installed CLI, not in Floci. A customization file in the CLI package, overridesslcommonname.py, fills in an SQS endpoint unless the user passed one. When I printed it, the condition only checks the parsed --endpoint-url flag. My reading is that it never consults AWS_ENDPOINT_URL, which matches what I observed. This is the v1 package from PyPI only. I did not test AWS CLI v2.

sed -n 117,125p overridesslcommonname.py
def update_endpoint_url(session, parsed_globals, **kwargs):
    service = parsed_globals.command
    endpoints = SSL_COMMON_NAMES.get(service)
    # only change url if user has not overridden already themselves
    if endpoints is not None and parsed_globals.endpoint_url is None:

Practically, an SQS call made this way is sent to the real AWS endpoint, with the dummy credentials. AWS rejected them here, so nothing was created, but it is an unpleasant surprise for a tool meant to keep traffic local. Passing --endpoint-url explicitly fixes it:

aws --endpoint-url http://localhost:4566 sqs create-queue --queue-name q1
{
    "QueueUrl": "http://localhost:4566/000000000000/q1"
}
aws --endpoint-url http://localhost:4566 sqs send-message --queue-url http://localhost:4566/000000000000/q1 --message-body hi --query MessageId
"c27660ff-2eab-44e0-8718-7e2aabcc384e"
aws --endpoint-url http://localhost:4566 sqs receive-message --queue-url http://localhost:4566/000000000000/q1 --query 'Messages[0].Body'
"hi"

The message I sent came back from the queue, so SQS works once the CLI is told the endpoint explicitly. An SDK is not affected. This is the whole boto3 script, with endpoint_url set on the client, and its output. For SQS from scripts, boto3 with an explicit endpoint worked.

cat /tmp/sqs_check.py
import boto3
c = boto3.client("sqs", endpoint_url="http://localhost:4566", region_name="us-east-1", aws_access_key_id="test", aws_secret_access_key="test")
print(c.meta.endpoint_url)
u = c.create_queue(QueueName="q2")["QueueUrl"]
c.send_message(QueueUrl=u, MessageBody="from boto3")
print(c.receive_message(QueueUrl=u)["Messages"][0]["Body"])
/tmp/awsenv/bin/python /tmp/sqs_check.py
http://localhost:4566
from boto3

Run part of the test suite

Counting files whose names end in Test.java under src/test gives 4081, and I did not run them all. I ran two integration classes, one for S3 and one for SQS, through Maven. The Quarkus test profile uses a random port, so it did not clash with the running service. First the count, then the run.

cd /tmp/floci; find src/test -name '*Test.java' | wc -l
4081
cd /tmp/floci; mvn -B test -Dtest='SqsIntegrationTest,S3IntegrationTest' > /tmp/test2.log 2>&1; grep -E "Tests run:|BUILD" /tmp/test2.log
[INFO] Tests run: 142, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 13.86 s -- in io.floci.aws.services.s3.S3IntegrationTest
[INFO] Tests run: 40, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 4.251 s -- in io.floci.aws.services.sqs.SqsIntegrationTest
[INFO] Tests run: 182, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

Limits and alternatives

What worked: with JDK 25 and a trust store that knows the egress CA, the documented build compiled, the jar started in a few seconds, S3, DynamoDB and SQS answered real requests, and 182 tests in two integration classes passed. What did not work out of the box was the environment, not Floci itself. The enforcer message is clear about the JDK, but nothing hints at the trust store, and the Maven output only says that artifacts could not be resolved.

The limits are plain. I ran no Docker-backed service, because there was no daemon, so Lambda, RDS and similar features are untested here. I ran two test classes, not the full suite. I used one JDK build on one machine, and I saw the AWS CLI v1 behaviour with one version only.

When to choose another route: if you have Docker, the image or the Floci CLI is faster than a source build and needs no JDK at all. If you only need the emulator running, the prebuilt native binary avoids both JDK walls, although I did not try it. Build from source when you want to run the tests or patch the code. With AWS CLI v1, pass --endpoint-url for SQS.