Floci

Floci es un emulador rápido, gratuito y open-source de servicios AWS para desarrollo local y CI. Está construido con Quarkus y compilado a binario nativo con GraalVM Mandrel. Arranca en ~24 ms, usa solo ~13 MiB en idle y es un reemplazo directo de LocalStack (mismo puerto 4566, mismas credenciales test/test y protocolos wire-compatibles).

A diferencia de otras soluciones, Floci no requiere token de autenticación, es 100 % MIT y ofrece más de 45 servicios AWS reales (muchos con motores Docker reales: Lambda, RDS PostgreSQL/MySQL, ElastiCache Redis, ECS, EKS, OpenSearch, etc.). Es especialmente útil para entornos JVM porque ofrece imagen Docker JVM dedicada y se puede ejecutar directamente como aplicación Java.

Ten presente que simula servicios AWS para desarrollo y pruebas. No sustituye un entorno productivo real, pero permite alta consistencia entre desarrollo y producción.

Instalación de Floci

La forma recomendada es usar Docker (imagen nativa por defecto).

Docker (recomendado)

docker pull floci/floci:latest
docker run --rm -p 4566:4566 floci/floci:latest

Imagen nativa: arranque ultrarrápido y bajo consumo.
Para compatibilidad JVM más amplia usa: floci/floci:latest-jvm

Verifica el estado (compatible con LocalStack):

curl http://localhost:4566/_localstack/health
# o
curl http://localhost:4566/_aws/health

Con persistencia (S3, DynamoDB, etc.)

docker run -d -p 4566:4566 \
  --name floci \
  -v ~/wsdata/floci:/app/data \
  -e FLOCI_STORAGE_MODE=persistent \
  floci/floci:latest

Docker Compose básico

services:
  floci:
    image: floci/floci:latest
    ports:
      - "4566:4566"
    volumes:
      - ./data:/app/data
    environment:
      FLOCI_STORAGE_MODE: hybrid

Para servicios que requieren contenedores reales (Lambda, RDS, ElastiCache) agrega:

    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Instalación directa para uso con JVM (sin Docker)

Floci se distribuye como aplicación Quarkus. Puedes ejecutarlo directamente con Java:

Requisitos de compilación:

• Java 25+
• Maven 3.9+

git clone https://github.com/floci-io/floci.git
cd floci

# Modo desarrollo con hot-reload
mvn quarkus:dev

# Build de JAR de producción
mvn clean package -DskipTests
java -jar target/quarkus-app/quarkus-run.jar

El JAR resultante (quarkus-run.jar) es un ejecutable JVM estándar. Puedes copiarlo a cualquier máquina con Java y ejecutarlo directamente:

java -jar floci-quarkus-run.jar

La imagen Docker floci/floci:latest-jvm ya trae el equivalente empaquetado y es la opción más sencilla si prefieres no compilar.

Probando con AWS CLI

export AWS_ENDPOINT_URL=http://localhost:4566
export AWS_DEFAULT_REGION=us-east-1
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test

aws s3 mb s3://mi-bucket-local
aws s3 ls

Instala AWS CLI con brew install awscli (macOS), sudo snap install aws-cli --classic (Linux) o el instalador oficial para Windows.

Probando Floci

A continuación exploramos ejemplos prácticos con el servicio S3. Necesitarás Node.js o Bun, o JBang para los ejemplos en Java.

Configuración del proyecto (JavaScript)

mkdir floci-test
cd floci-test
npm init -y
npm install @aws-sdk/client-s3

Ejemplo con S3 (JavaScript)

import { S3Client, PutObjectCommand, GetObjectCommand, ListBucketsCommand } from "@aws-sdk/client-s3";

const s3Client = new S3Client({
  endpoint: "http://localhost:4566",
  region: "us-east-1",
  credentials: {
    accessKeyId: "test",
    secretAccessKey: "test"
  },
  forcePathStyle: true
});

async function main() {
  // Crear bucket
  await s3Client.send(new PutObjectCommand({
    Bucket: "mi-bucket-local",
    Key: "saludo.txt",
    Body: "¡Hola desde Floci!",
    ContentType: "text/plain"
  }));
  console.log("Archivo subido");

  // Listar
  const buckets = await s3Client.send(new ListBucketsCommand({}));
  console.log("Buckets:", buckets.Buckets);

  // Descargar
  const obj = await s3Client.send(new GetObjectCommand({
    Bucket: "mi-bucket-local",
    Key: "saludo.txt"
  }));
  console.log("Contenido:", await obj.Body.transformToString());
}

main().catch(console.error);

Ejecuta:

node index.js

Ejemplo con S3 (Java con JBang + AWS SDK v2)

Crea el archivo FlociS3Example.java:

///usr/bin/env jbang "$0" "$@" ; exit $?
//DEPS software.amazon.awssdk:s3:2.30.0

import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;

import java.net.URI;

public class FlociS3Example {

    public static void main(String[] args) {
        try (S3Client s3 = S3Client.builder()
                .endpointOverride(URI.create("http://localhost:4566"))
                .region(Region.US_EAST_1)
                .credentialsProvider(StaticCredentialsProvider.create(
                        AwsBasicCredentials.create("test", "test")))
                .forcePathStyle(true)
                .build()) {

            // Crear bucket + objeto
            s3.createBucket(b -> b.bucket("mi-bucket-local"));
            s3.putObject(p -> p.bucket("mi-bucket-local")
                               .key("saludo.txt")
                               .contentType("text/plain"),
                    software.amazon.awssdk.core.sync.RequestBody.fromString("¡Hola desde Floci con JBang!"));

            // Listar buckets
            s3.listBuckets().buckets()
              .forEach(b -> System.out.println("Bucket: " + b.name()));

            // Leer objeto
            String content = s3.getObjectAsBytes(g -> g.bucket("mi-bucket-local")
                .key("saludo.txt"))
                .asUtf8String();
            System.out.println("Contenido: " + content);
        }
    }
}

Ejecuta directamente (JBang descarga las dependencias automáticamente):

jbang FlociS3Example.java

Con Floci obtienes un entorno AWS local extremadamente ligero, rápido de arrancar y con excelente soporte para ecosistemas JVM (imágenes JVM, JAR ejecutable, integración nativa con Testcontainers y Spring Boot).