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
• Faire démarrer de vraies instances EC2 via le socket Docker
• 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, a fermé l'accès libre de son édition Community. Depuis la version 2026.03.0 (mars 2026), l'image localstack/localstack unique exige un jeton d'authentification lié à un compte (un plan gratuit existe pour les usages individuels), et l'ancien dépôt open-source a été archivé (annonces LocalStack de mars 2026). Floci se positionne comme l'alternative MIT, sans compte et sans jeton.

Projet jeune, à valider pour vos cas

Floci est récent (premières versions début 2026) et progresse vite. Il annonce une large couverture de services, mais la profondeur varie selon les API. Traitez-le comme un accélérateur de dev et de tests, et validez chaque service que vous comptez utiliser sur vos propres scénarios avant d'en dépendre.

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 run -d --name floci -p 127.0.0.1:4566:4566 \
  floci/floci:2.2.0@sha256:e97cd0c1dc2aa14e7697fb5ef5018404c4d6345169dbd276315f0bed2c7b0520

Docker Compose

Créez un fichier compose.yaml :

services:
  floci:
    container_name: floci
    image: floci/floci:2.2.0@sha256:e97cd0c1dc2aa14e7697fb5ef5018404c4d6345169dbd276315f0bed2c7b0520
    ports:
      - "127.0.0.1:4566:4566"

Puis démarrez :

docker compose up -d

Vérifiez que le conteneur est prêt. L'image est native (Quarkus). Sans socket Docker monté, Floci tente d'abord de joindre le démon Docker et réessaie plusieurs fois : comptez une quinzaine de secondes avant la ligne Listening on, et attendez-la avant de lancer vos commandes AWS (sinon l'AWS CLI répond Connection was closed). Avec le socket monté (section EC2 plus bas), le démarrage prend moins d'une seconde :

docker logs floci | grep 'Listening on'

La sortie doit afficher une ligne du type floci 2.2.0 native ... started ... Listening on: http://0.0.0.0:4566. L'adresse 0.0.0.0 est celle dans le conteneur ; côté hôte, docker port floci doit répondre 4566/tcp -> 127.0.0.1:4566, signe que le port n'est pas exposé au réseau.

Les commandes de ce guide combinent le tag 2.2.0, lisible par un humain, et l'empreinte @sha256:..., qui fige le contenu exact de l'image : le tag seul peut être repointé vers une autre image, l'empreinte ne peut pas. Cette forme tag@sha256 est celle à reproduire dans votre CI pour une chaîne d'approvisionnement maîtrisée.

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 = "~> 6.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 rm -f floci 2>/dev/null
docker run -d --name floci \
  -p 127.0.0.1:4566:4566 \
  -u root \
  -v /var/run/docker.sock:/var/run/docker.sock \
  floci/floci:2.2.0@sha256:e97cd0c1dc2aa14e7697fb5ef5018404c4d6345169dbd276315f0bed2c7b0520

Docker Compose

services:
  floci:
    container_name: floci
    image: floci/floci:2.2.0@sha256:e97cd0c1dc2aa14e7697fb5ef5018404c4d6345169dbd276315f0bed2c7b0520
    user: root
    ports:
      - "127.0.0.1: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.

Le socket Docker équivaut à un accès root sur l'hôte

Un processus qui peut parler au socket Docker peut lancer un conteneur privilégié qui monte le système de fichiers de l'hôte : c'est un accès root sur la machine. Ici, Floci tourne en root et commande le démon. Réservez ce montage à un poste de développement ou à un runner CI jetable, jamais à un serveur partagé, et n'exposez pas le port 4566 hors de localhost (les commandes de cette page le publient déjà sur 127.0.0.1). Pour S3 et DynamoDB, qui n'en ont pas besoin, ne montez pas le 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-aws-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

Glissez pour voir

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

N'émulez pas tout l'AWS

L'émulation locale est parfaite pour développer et tester la logique (appels d'API, modules IaC, intégration). Elle ne remplace pas un test de bout en bout sur un vrai compte avant la production : les comportements fins (IAM, cohérence, quotas, limites de service) diffèrent. Gardez un environnement réel pour la validation finale.

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 (en mémoire par défaut, persistant selon le mode de stockage vu plus haut). 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.

Comment nettoyer l'environnement Floci ?

Pour tout remettre à zéro, supprimez le conteneur puis retirez les variables exportées dans votre terminal, sans quoi vos outils AWS continueraient de viser l'émulateur localhost:4566 ou d'utiliser les identifiants factices. Avec Docker Compose, docker compose down joue le rôle de docker rm -f floci.

docker ps -aq --filter name=floci-aws- | xargs -r docker rm -f
docker rm -f floci
docker network ls -q --filter name=floci-aws- | xargs -r docker network rm
unset AWS_ENDPOINT_URL AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY

Les conteneurs de backing (par exemple floci-aws-ec2-<id> pour une instance EC2) survivent à la suppression de floci : la première ligne les retire, et la troisième supprime le réseau floci-aws-vpc-... que Floci a créé. Sans elles, docker compose down signale Resource is still in use sur le réseau Compose.

Vérifiez avec docker ps -a que plus aucun conteneur floci n'apparaît, et avec env | grep AWS_ que ni AWS_ENDPOINT_URL ni les clés d'accès ne restent exportées (AWS_DEFAULT_REGION, inoffensive, peut rester).

Dépannage

Ce tableau sert à diagnostiquer une erreur en partant de ce que vous voyez. Repérez le symptôme dans la première colonne, vérifiez la cause probable, puis appliquez la solution de la dernière colonne avant de chercher plus loin.

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
Une instance EC2 reste en pending	Socket Docker non monté ou Floci non lancé en root	Relancer avec -u root -v /var/run/docker.sock:/var/run/docker.sock
Un service répond not implemented	API non couverte par cette version	Vérifier la version de Floci, épingler une version compatible

Glissez pour voir

À 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é (depuis 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 (forme tag@sha256), jamais latest
• L'émulation accélère dev, tests et CI, mais ne remplace pas une validation réelle avant production

FAQ

Cette section regroupe les questions fréquentes sur Floci et son usage comme émulateur AWS local. Chaque question reçoit une réponse courte, à compléter par les chapitres précédents si le sujet vous concerne.

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

Floci est-il vraiment gratuit ?

Quels services AWS Floci émule-t-il ?

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

Comment brancher Terraform sur Floci ?

Monter le socket Docker dans Floci est-il risqué ?

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.

×

📖 Voir la documentation →