Skip to content

armgit / floci

Public Imported from GitHub
0

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

fix: release 1.5.5

Hector Venturab7774d17b2a9
diff --git a/README.md b/README.md
index 800cf00974..76d2e763c6 100644
--- a/README.md
+++ b/README.md
@@ -59,7 +59,7 @@
| EC2 (VPCs, instances, security groups) | ✅ | ⚠️ Partial |
| Native binary | ✅ ~40 MB | ❌ |
-**Broad AWS coverage. 1,850+ automated compatibility tests. Free forever.**
+**Broad AWS coverage. Free forever.**
## Architecture Overview
@@ -93,6 +93,69 @@ flowchart LR
Containers -->|"Docker API\n+ IAM / SigV4 auth"| Docker
```
+## Real Docker Integration
+
+Unlike mock-only emulators, Floci runs **real Docker containers** for services where in-process emulation would compromise fidelity — stateful databases, connection-heavy protocols, and runtimes that require native execution. The result is wire-compatible behavior against the actual engine, not a simplified approximation.
+
+| Service | Default Docker image | What's real |
+|---|---|---|
+| **Lambda** | `public.ecr.aws/lambda/<runtime>` | AWS runtime environment, execution model, warm container pool |
+| **ElastiCache** | `valkey/valkey:8` | Full Redis/Valkey protocol, ACL-based IAM auth, SigV4 validation |
+| **RDS (PostgreSQL)** | `postgres:16-alpine` | Real PostgreSQL engine, IAM auth via token, JDBC-compatible |
+| **RDS (MySQL / Aurora)** | `mysql:8.0` | Real MySQL engine, IAM auth, JDBC-compatible |
+| **RDS (MariaDB)** | `mariadb:11` | Real MariaDB engine, IAM auth, JDBC-compatible |
+| **MSK** | `redpandadata/redpanda:latest` | Real Kafka-compatible broker via Redpanda |
+| **ECS** | User-specified in task definition | Actual container lifecycle — start, stop, health checks |
+| **EKS** | `rancher/k3s:latest` | Live Kubernetes API server (k3s), full kubeconfig |
+| **OpenSearch** | `opensearchproject/opensearch:2` | Full OpenSearch engine with REST API |
+| **ECR** | `registry:2` | Real OCI-compatible registry — `docker push` / `docker pull` work natively |
+
+### Lambda runtimes
+
+Floci resolves each Lambda runtime to the corresponding [AWS public ECR image](https://gallery.ecr.aws/lambda):
+
+| Runtime | Image |
+|---|---|
+| `java25` · `java21` · `java17` · `java11` · `java8.al2` · `java8` | `public.ecr.aws/lambda/java:<version>` |
+| `python3.14` · `python3.13` · `python3.12` · `python3.11` · `python3.10` · `python3.9` | `public.ecr.aws/lambda/python:<version>` |
+| `nodejs24.x` · `nodejs22.x` · `nodejs20.x` · `nodejs18.x` · `nodejs16.x` | `public.ecr.aws/lambda/nodejs:<version>` |
+| `ruby3.4` · `ruby3.3` · `ruby3.2` | `public.ecr.aws/lambda/ruby:<version>` |
+| `dotnet10` · `dotnet9` · `dotnet8` · `dotnet6` | `public.ecr.aws/lambda/dotnet:<version>` |
+| `go1.x` | `public.ecr.aws/lambda/go:1` |
+| `provided.al2023` · `provided.al2` · `provided` | `public.ecr.aws/lambda/provided:<variant>` |
+
+Container image functions (package type `Image`) pass the `ImageUri` through directly, with ECR repository URIs rewritten to the local Floci ECR endpoint automatically.
+
+### Requirements
+
+Docker-backed services require the Docker socket to be accessible:
+
+```bash
+docker run -d --name floci \
+ -p 4566:4566 \
+ -v /var/run/docker.sock:/var/run/docker.sock \
+ -u root \
+ hectorvent/floci:latest
+```
+
+In Docker Compose, add the socket volume alongside any other mounts.
+
+### Overriding default images
+
+All default images are configurable via environment variables, useful for pinning versions or using a local mirror:
+
+| Variable | Default |
+|---|---|
+| `FLOCI_SERVICES_ELASTICACHE_DEFAULT_IMAGE` | `valkey/valkey:8` |
+| `FLOCI_SERVICES_RDS_DEFAULT_POSTGRES_IMAGE` | `postgres:16-alpine` |
+| `FLOCI_SERVICES_RDS_DEFAULT_MYSQL_IMAGE` | `mysql:8.0` |
+| `FLOCI_SERVICES_RDS_DEFAULT_MARIADB_IMAGE` | `mariadb:11` |
+| `FLOCI_SERVICES_MSK_DEFAULT_IMAGE` | `redpandadata/redpanda:latest` |
+| `FLOCI_SERVICES_OPENSEARCH_DEFAULT_IMAGE` | `opensearchproject/opensearch:2` |
+| `FLOCI_SERVICES_EKS_DEFAULT_IMAGE` | `rancher/k3s:latest` |
+| `FLOCI_SERVICES_ECR_REGISTRY_IMAGE` | `registry:2` |
+| `FLOCI_ECR_BASE_URI` | `public.ecr.aws` (Lambda runtime base) |
+
## Supported Services
| Service | How it works | Notable features |
@@ -450,6 +513,7 @@ Available compatibility test modules:
| `compat-opentofu` | OpenTofu | v1.9+ | 14 |
| `compat-cdk` | AWS CDK | v2+ | 17 |
+**1,850+ automated compatibility tests across 6 SDKs and 3 IaC tools.**
## Image Tags
@@ -465,7 +529,7 @@ All settings are overridable via environment variables (`FLOCI_` prefix).
| Variable | Default | Description |
|---|---|-------------------------------------------------------------------------------------|
-| `QUARKUS_HTTP_PORT` | `4566` | Port exposed by the Floci API |
+| `FLOCI_PORT` | `4566` | Port exposed by the Floci API |
| `FLOCI_DEFAULT_REGION` | `us-east-1` | Default AWS region |
| `FLOCI_DEFAULT_ACCOUNT_ID` | `000000000000` | Default AWS account ID |
| `FLOCI_BASE_URL` | `http://localhost:4566` | Base URL used when Floci returns service URLs (e.g. SQS QueueUrl) |
diff --git a/floci_banner.svg b/floci_banner.svg
index fed0f6d79d..9fa322d636 100644
--- a/floci_banner.svg
+++ b/floci_banner.svg
@@ -108,7 +108,7 @@
<!-- Stat 3: Services -->
<text x="770" y="548"
font-family="'Courier New', Courier, monospace"
- font-size="42" font-weight="700" fill="#ffe082" text-anchor="middle">29
+ font-size="42" font-weight="700" fill="#ffe082" text-anchor="middle">~35
</text>
<text x="770" y="574"
font-family="'Helvetica Neue', Helvetica, Arial, sans-serif"
diff --git a/pom.xml b/pom.xml
index 6920255ab8..993900fe9a 100644
--- a/pom.xml
+++ b/pom.xml
@@ -6,7 +6,7 @@
<groupId>io.github.hectorvent</groupId>
<artifactId>floci</artifactId>
- <version>1.5.4</version>
+ <version>1.5.5</version>
<packaging>jar</packaging>
<name>Floci</name>
diff --git a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java
index 7884ba59a9..a17f4a1e21 100644
--- a/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java
+++ b/src/main/java/io/github/hectorvent/floci/config/EmulatorConfig.java
@@ -7,6 +7,9 @@ import java.util.Optional;
@ConfigMapping(prefix = "floci")
public interface EmulatorConfig {
+ @WithDefault("4566")
+ int port();
+
@WithDefault("http://localhost:4566")
String baseUrl();
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
index 63d6fd1ea5..4f3cf92bb0 100644
--- a/src/main/resources/application.yml
+++ b/src/main/resources/application.yml
@@ -1,6 +1,6 @@
quarkus:
http:
- port: 4566
+ port: ${floci.port}
host: 0.0.0.0
limits:
max-body-size: ${floci.max-request-size}M
@@ -22,6 +22,7 @@ quarkus:
--initialize-at-run-time=io.github.hectorvent.floci.services.cognito.CognitoSrpHelper
floci:
+ port: 4566
max-request-size: 512
base-url: "http://localhost:4566"
# hostname: "" # When set, overrides the hostname in response URLs (e.g. SQS QueueUrl).
diff --git a/src/test/java/io/github/hectorvent/floci/services/eventbridge/EventBridgeSchedulerIntegrationTest.java b/src/test/java/io/github/hectorvent/floci/services/eventbridge/EventBridgeSchedulerIntegrationTest.java
index f572a48dcf..4b5c428ee9 100644
--- a/src/test/java/io/github/hectorvent/floci/services/eventbridge/EventBridgeSchedulerIntegrationTest.java
+++ b/src/test/java/io/github/hectorvent/floci/services/eventbridge/EventBridgeSchedulerIntegrationTest.java
@@ -275,6 +275,8 @@ class EventBridgeSchedulerIntegrationTest {
private EmulatorConfig createConfig() {
return new EmulatorConfig() {
+ @Override
+ public int port() { return 4566; }
@Override
public String baseUrl() { return "http://localhost:4566"; }
@Override