Floci : émuler AWS en local pour développer et tester

Floci est un émulateur AWS local open-source (licence MIT) qui expose des services AWS sur votre machine, sans compte cloud, sans jeton d'authentification et sans payer. Vous pointez votre AWS CLI, vos SDK, Terraform ou OpenTofu sur http://localhost:4566 et vos outils fonctionnent comme face au vrai AWS. Ce guide montre comment démarrer Floci avec Docker, brancher vos outils existants, et valider le tout sur S3, DynamoDB et un déploiement Terraform. Public visé : développeurs et DevOps qui veulent un environnement AWS reproductible pour le développement, les tests et la CI.

Ce que vous allez apprendre

Démarrer Floci avec Docker (image épinglée, jamais latest)
Configurer l'environnement AWS local (endpoint, région, identifiants)
Utiliser AWS CLI et Terraform contre l'émulateur
Cerner la portée réelle et les limites de l'émulation

Pourquoi un émulateur AWS local

Développer directement contre le vrai AWS coûte de l'argent, exige un compte et des identifiants, et rend les tests lents et fragiles (latence réseau, état partagé, nettoyage à faire). Un émulateur local donne des services « AWS-compatibles » sur votre poste : création instantanée, isolation totale, zéro facture, et une CI qui ne dépend ni d'un compte ni de la disponibilité du cloud.

Floci occupe ce créneau au moment où LocalStack, l'émulateur historique, ferme l'accès libre de son édition Community. À partir de mars 2026, l'image localstack/localstack:latest exigera un jeton d'authentification lié à un compte, les correctifs de sécurité ne seront plus appliqués qu'à la version authentifiée, et le dépôt open-source passera en mode inactif. Floci se positionne comme l'alternative MIT, sans compte et sans jeton.

Prérequis

Docker installé et démarré (docker --version).
L'AWS CLI v2 (aws --version) pour les exemples en ligne de commande.
Facultatif : Terraform ou OpenTofu pour la partie infrastructure as code.

Démarrer Floci

Floci se lance comme un simple conteneur qui écoute sur le port 4566, le même que LocalStack. N'utilisez jamais le tag latest : épinglez une version précise pour des environnements reproductibles.

Docker
Docker Compose

docker run -d --name floci -p 4566:4566 floci/floci:1.5.27

Créez un fichier compose.yaml :

services:
  floci:
    image: floci/floci:1.5.27@sha256:78ee619e895a01a5c0db9d1037082bf487807290583a4e78300de2b6e041a9b1
    ports:
      - "4566:4566"

Puis démarrez :

docker compose up -d

Vérifiez que le conteneur est prêt. Floci démarre en moins d'une seconde (image native Quarkus) :

docker logs floci | tail -1

La sortie doit afficher une ligne du type floci 1.5.27 native ... started ... Listening on: http://0.0.0.0:4566.

Pour une reproductibilité totale (chaîne d'approvisionnement), épinglez par empreinte @sha256 plutôt que par tag, afin que l'image ne puisse pas être remplacée silencieusement :

docker run -d --name floci -p 4566:4566 \
  floci/floci@sha256:78ee619e895a01a5c0db9d1037082bf487807290583a4e78300de2b6e041a9b1

Brancher vos outils AWS

Floci accepte n'importe quels identifiants non vides et n'importe quelle région. Exportez l'environnement AWS une fois pour toutes dans votre shell :

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

La variable AWS_ENDPOINT_URL est la clé : elle redirige l'AWS CLI v2 et la plupart des SDK vers l'émulateur, sans toucher à votre code applicatif.

Premier test avec S3

Créez un bucket, déposez un objet, listez le résultat :

aws s3 mb s3://lab-bucket
echo "contenu de test" > objet.txt
aws s3 cp objet.txt s3://lab-bucket/objet.txt
aws s3 ls s3://lab-bucket/

La sortie doit lister objet.txt avec sa taille. Vous venez d'utiliser l'API S3 sans compte AWS ni le moindre octet envoyé dans le cloud.

Un service avec état : DynamoDB

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

aws dynamodb list-tables

La table passe à l'état ACTIVE et apparaît dans list-tables. L'état est conservé tant que le conteneur tourne.

Déployer avec Terraform

L'intérêt principal d'un émulateur, c'est de tester votre infrastructure as code sans rien provisionner de réel. On configure le fournisseur AWS de Terraform pour qu'il vise Floci, via le bloc endpoints et quelques options qui désactivent les vérifications d'identité inutiles en local.

terraform {
  required_providers {
    aws = { source = "hashicorp/aws", version = "~> 5.0" }
  }
}

provider "aws" {
  region                      = "us-east-1"
  access_key                  = "test"
  secret_key                  = "test"
  skip_credentials_validation = true
  skip_requesting_account_id  = true
  skip_metadata_api_check     = true
  s3_use_path_style           = true

  endpoints {
    s3       = "http://localhost:4566"
    dynamodb = "http://localhost:4566"
  }
}

resource "aws_s3_bucket" "lab" {
  bucket = "terraform-drop-in"
}

resource "aws_dynamodb_table" "lab" {
  name         = "tf-table"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "id"

  attribute {
    name = "id"
    type = "S"
  }
}

Déployez puis vérifiez :

terraform init
terraform apply -auto-approve
aws s3 ls            # terraform-drop-in apparaît
aws dynamodb list-tables   # tf-table apparaît

Terraform affiche Apply complete! Resources: 2 added, et l'AWS CLI confirme que les ressources existent côté Floci. Votre module Terraform est validé sans compte AWS, gratuitement, en quelques secondes.

Faire démarrer de vraies instances EC2

Une instance EC2 créée sur Floci reste à l'état pending tant que l'émulateur ne peut pas la faire tourner. Pour qu'elle passe en running, montez le socket Docker dans le conteneur Floci et lancez-le en root : RunInstances crée alors un vrai conteneur Linux par instance, avec injection de la clé SSH, exécution du UserData et support de l'IMDS.

C'est le même prérequis pour tous les services conteneurisés de Floci : EC2, ECS, Lambda, RDS et EKS reposent sur une exécution Docker réelle, pas sur de simples bouchons (mocks). S3 et DynamoDB, eux, n'en ont pas besoin.

Docker
Docker Compose

docker rm -f floci 2>/dev/null
docker run -d --name floci \
  -p 4566:4566 \
  -u root \
  -v /var/run/docker.sock:/var/run/docker.sock \
  floci/floci:1.5.27

services:
  floci:
    image: floci/floci:1.5.27@sha256:78ee619e895a01a5c0db9d1037082bf487807290583a4e78300de2b6e041a9b1
    user: root
    ports:
      - "4566:4566"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Le montage de /var/run/docker.sock donne à Floci la main sur le démon Docker de l'hôte pour lancer les conteneurs de backing ; l'option -u root (ou user: root en Compose) lui donne les droits d'accès au socket.

Créez une instance. Floci ignore l'AMI fournie et retombe sur son image par défaut public.ecr.aws/amazonlinux/amazonlinux:2023 : n'importe quel ami-xxxxxxxx convient (le journal affiche alors Unknown AMI ID ...; falling back to default image).

aws ec2 run-instances \
  --image-id ami-00000000 \
  --instance-type t3.micro \
  --count 1

Le passage à running n'est pas instantané : Floci crée puis démarre le conteneur de backing (injection de la clé SSH, IMDS), ce qui prend quelques secondes. Laissez la transition se faire avant de vérifier l'état :

aws ec2 describe-instances \
  --query 'Reservations[].Instances[].[InstanceId,State.Name]' \
  --output table

Une fois l'instance en running, docker ps liste le conteneur floci-ec2-<id> qui la porte, avec un port SSH exposé sur l'hôte. Côté Terraform, il suffit d'ajouter ec2 (et les autres services voulus) au bloc endpoints du provider :

  endpoints {
    ec2      = "http://localhost:4566"
    s3       = "http://localhost:4566"
    dynamodb = "http://localhost:4566"
  }

Conserver l'état entre deux exécutions

Par défaut, Floci garde l'état en mémoire (FLOCI_STORAGE_MODE=memory) : tout disparaît à l'arrêt du conteneur, ce qui convient parfaitement à la CI. Pour retrouver vos ressources après un redémarrage, choisissez un mode persistant :

`FLOCI_STORAGE_MODE`	Comportement	Usage
`memory` (défaut)	état en RAM, perdu à l'arrêt	CI, tests jetables
`persistent`	écriture disque immédiate à chaque mutation	durabilité maximale
`hybrid`	vitesse RAM plus flush asynchrone toutes les 5 s	dev au long cours
`wal`	journalisation avant écriture (write-ahead log)	durabilité sans perte

Le répertoire de persistance se règle avec FLOCI_STORAGE_PERSISTENT_PATH (défaut ./data).

Portée et limites

Floci annonce une large couverture de services AWS. Certains, comme Lambda, RDS, ECS, EC2 ou EKS, s'appuient sur une exécution Docker réelle plutôt que sur de simples bouchons (mocks), tandis que S3 et DynamoDB gardent un état persistant. Cette approche rapproche le comportement de l'émulateur du vrai AWS pour les services conteneurisés. Ces services exigent le montage du socket Docker vu plus haut : sans lui, une instance EC2 reste bloquée en pending.

Deux points de vigilance, propres à tout émulateur et accentués par la jeunesse du projet :

La profondeur d'une API émulée n'égale pas toujours celle d'AWS : une fonctionnalité avancée peut manquer ou différer.
La maintenance repose sur un projet récent : épinglez vos versions et suivez les évolutions avant d'en faire une brique critique de votre CI.

Dépannage

Symptôme	Cause probable	Solution
`Could not connect to the endpoint URL`	Conteneur pas prêt ou mauvais port	Vérifier `docker ps` et que le port 4566 est mappé
`InvalidClientTokenId` ou erreurs d'identité	Variables AWS non exportées	Réexporter `AWS_ENDPOINT_URL` et des identifiants non vides
Terraform ignore l'endpoint	Bloc `endpoints` absent ou service non listé	Ajouter le service dans `endpoints { ... }` du provider
Un service répond `not implemented`	API non couverte par cette version	Vérifier la version de Floci, épingler une version compatible

À retenir

Floci émule AWS en local (MIT), sur http://localhost:4566, sans compte ni jeton
Il arrive au moment où LocalStack Community bascule en accès authentifié (mars 2026)
AWS_ENDPOINT_URL suffit à rediriger AWS CLI et SDK vers l'émulateur
Terraform vise Floci via le bloc endpoints : IaC testée gratuitement
EC2/ECS/Lambda/RDS/EKS : montez /var/run/docker.sock et lancez Floci en root pour que les instances passent en running
Épinglez toujours une version (idéalement par empreinte @sha256), jamais latest
L'émulation accélère dev, tests et CI, mais ne remplace pas une validation réelle avant production

FAQ

Pourquoi mon instance EC2 reste-t-elle en `pending` sur Floci ?

Parce que le socket Docker n'est pas monté : sans lui, Floci ne peut pas lancer le conteneur qui porte l'instance. Démarrez le conteneur avec -u root -v /var/run/docker.sock:/var/run/docker.sock et l'instance passe en running.

Floci est-il vraiment gratuit ?

Oui : Floci est open-source sous licence

MIT**, sans compte ni jeton d'authentification, au moment où l'édition Community de LocalStack bascule en accès authentifié (mars 2026). **Quels services AWS Floci émule-t-il ?

S3 et DynamoDB avec état persistant, et des services conteneurisés (EC2, ECS, Lambda, RDS, EKS) portés par de vrais conteneurs Docker. La profondeur varie selon les API : validez chaque service sur votre scénario avant d'en dépendre.

Floci fonctionne-t-il en intégration continue ?

Oui, c'est son terrain de prédilection : un conteneur sur le port 4566, le mode de stockage memory par défaut et aucun compte cloud. Épinglez l'image par version ou par empreinte @sha256.

Comment brancher Terraform sur Floci ?

Configurez le provider aws avec un bloc endpoints pointant vers http://localhost:4566, plus skip_credentials_validation, skip_requesting_account_id, skip_metadata_api_check et des identifiants factices non vides.

Prochaines étapes

Découvrir les services AWS Les fondamentaux d'AWS que Floci reproduit en local.

Maîtriser l'AWS CLI La ligne de commande que vous pointez sur l'émulateur.

Provisionner AWS avec Terraform Écrire l'infrastructure as code que vous validez d'abord sur Floci.

Serverless et FaaS Tester localement vos fonctions avant de les déployer.