floci

Floci

Floci emulates AWS services on your machine (dev/CI) without a cloud account. Point SDK, CLI and IaC at the endpoint — same workflows, dummy credentials.

Product name: Floci (floci-io/floci). Default endpoint: http://localhost:4566.

Stack and scope

Piece	Role
floci/floci	Docker image / emulator runtime
:4566	Single AWS-compatible endpoint
AWS SDK / CLI / Terraform	Existing clients with endpoint_url
Volume /app/data	Optional local persistence

There are sibling emulators (Azure/GCP/OCI) in the Floci ecosystem; this skill focuses on the AWS (floci/floci).

Start Floci

# docker-compose.yml
services:
  floci:
    image: floci/floci:latest
    ports:
      - "4566:4566"
    volumes:
      - ./data:/app/data

docker compose up -d

• latest = native image (fast startup). latest-jvm if you need platform compatibility.
• Mount a volume if you want data across restarts.

CLI and env

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://my-bucket
aws sqs create-queue --queue-name orders
aws dynamodb create-table \
  --table-name Users \
  --attribute-definitions AttributeName=id,AttributeType=S \
  --key-schema AttributeName=id,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

With AWS_ENDPOINT_URL set, the recent CLI uses the emulator; otherwise pass --endpoint-url.

SDKs

Node (AWS SDK v3) — S3 usually requires path-style:

import { S3Client } from "@aws-sdk/client-s3";

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

Python (boto3):

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="http://localhost:4566",
    region_name="us-east-1",
    aws_access_key_id="test",
    aws_secret_access_key="test",
)

Go: configure the endpoint in the AWS SDK v2 config (project base-endpoint / resolver) pointing at http://localhost:4566, region and dummy credentials.

• Centralize the endpoint via env (AWS_ENDPOINT_URL / app config) — never hardcode it in just one client.
• In Docker Compose with the app in another container: use the service hostname (http://floci:4566) and, if Floci docs require it, FLOCI_HOSTNAME for URLs resolvable between containers.

Common services in tests

Service	Typical use in dev/CI
S3	Upload/download, presign (as supported)
SQS / SNS	Queues and pub/sub
DynamoDB	On-demand tables
Secrets Manager / SSM	Local config
Lambda / ECR	Functions and images (requires Docker)
EventBridge / Step Functions	Local orchestration

Check the per-service surface in the Floci docs — not every AWS API exists or is complete.

CI and practices

• Start Floci as a job service; smoke test (S3 mb + put) before the suite.
• Credentials test/test; never point production at Floci by mistake (keep the endpoint behind env APP_ENV=local|test).
• Prefer asserts on app behavior over relying on the emulator's internal details.
• Container-backed services (Lambda, RDS, ElastiCache, etc.) need Docker available on the host/CI.

Anti-patterns

• Mixing the Floci endpoint with real production credentials
• Assuming 100% parity with AWS without checking the operation
• Hardcode localhost:4566 inside shared libs without an override
• Forgetting forcePathStyle in S3 (JS SDK) and blaming the emulator
• Persisting sensitive data in the Floci volume carelessly

Completion criteria

• Floci starts and responds at the configured endpoint
• CLI or SDK can do at least one smoke test (S3/SQS/DDB)
• Local app/CI points to the endpoint via config/env
• Dummy credentials isolated from the prod environment
• Services used by the feature covered by the emulator (or documented alternative mock)