Using floci to emulate Cloud platforms (GCP, AWS, Azure)

Recommendation – Use FLOCI when a single Docker‑based emulator meets most of your local development needs

Choose FLOCI if you need a lightweight, Docker‑hosted emulator that can expose a limited set of GCP, AWS, and Azure services together. It works well for teams that only require object storage, simple messaging, and basic NoSQL or document databases.

If your code depends on a wide range of cloud APIs, on advanced features such as fine‑grained IAM, VPC networking, or managed Kubernetes, or if you need production‑grade fidelity, supplement FLOCI with provider‑specific emulators (for example, LocalStack for AWS, the Google Cloud SDK gcloud beta emulators, or Azure Storage Emulator).

The core trade‑off is scope versus completeness. FLOCI offers a unified Docker image and a single endpoint, which reduces orchestration effort and speeds up CI pipelines. In return you accept partial API coverage, occasional incompatibilities after version upgrades, and the need to manage authentication stubs yourself. For many micro‑service projects the convenience outweighs the gaps; for larger, compliance‑sensitive workloads a mixed‑tool approach remains safer.

---

FLOCI Overview & Key Tradeoffs

What FLOCI is

FLOCI (pronounced “flow‑see”) is an open‑source project that packages a set of cloud‑service stubs inside one Docker image. It implements a small, well‑defined subset of the public REST/JSON APIs for Google Cloud Platform (GCP), Amazon Web Services (AWS), and Microsoft Azure. A built‑in HTTP router forwards requests to the appropriate mock based on the hostname or path prefix you configure.

Core architecture

How FLOCI differs from other local emulators

Key trade‑offs

• Simplicity vs. coverage – A single‑image design reduces orchestration effort but limits the number of services you can emulate.
• Speed vs. realism – Mocks store data locally and skip many security checks, so start‑up is fast. Code that relies on fine‑grained IAM or regional behavior may see different results in production.
• Version lock‑in – FLOCI tracks specific API versions (e.g., GCP Pub/Sub v1). Updating the Docker image can introduce breaking changes; verify compatibility before a major bump.

If these trade‑offs match your workflow, proceed with FLOCI. Otherwise, adopt a mixed‑toolchain approach.

---

Supported Services & Known Gaps

The table below reflects the services implemented in the latest stable FLOCI release (v0.9.1). Versions refer to the public API version that each mock aims to emulate. Check the repository’s SUPPORTED_SERVICES.md file for the most current list.

Known gaps

• IAM / authentication – FLOCI accepts any request that contains a correctly formatted Authorization header but does not validate signatures or enforce policies. Tests that need permission‑error handling must mock those responses manually.
• Regional behavior – All services run in a single logical region (local). Features that differ by region (latency‑based routing, data residency, etc.) are not reproduced.
• Advanced services – AWS Kinesis, GCP BigQuery, Azure Event Hubs, managed Kubernetes, and similar services are outside the current scope.
• Version drift – The mock API may lag behind the latest provider release. If your code uses a newly added field, FLOCI will return an “unknown parameter” error.

When a required service is missing or a limitation blocks a test, you can run the provider‑specific emulator for that service alongside FLOCI.

---

Multi‑Provider Setup & Configuration

The steps below assume Docker Engine (or Docker Desktop) and Docker Compose v2 are installed. Commands are shown for a Unix‑like shell; equivalent PowerShell commands are similar.

1. Pull the FLOCI image

docker pull ghcr.io/floci/floci:0.9.1

Replace 0.9.1 with a newer tag if one is available.

2. Create a docker-compose.yml

version: "3.9"

services:
  floci:
    image: ghcr.io/floci/floci:0.9.1
    container_name: floci
    ports:
      - "8080:8080"
    environment:
      - ENABLE_AWS_S3=true
      - ENABLE_AWS_SQS=true
      - ENABLE_GCP_STORAGE=true
      - ENABLE_GCP_PUBSUB=true
      - ENABLE_AZURE_BLOB=true
      - ENABLE_AZURE_QUEUE=true
    volumes:
      - ./floci-data:/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/healthz"]
      interval: 10s
      timeout: 5s
      retries: 3

Key points

• Ports – FLOCI listens on a single port (8080). Your application reaches any mock service by using the appropriate hostname prefix (see step 4).
• Environment variables – Each ENABLE_* flag turns a specific mock on or off, reducing memory use for unused services.
• Volumes – Mounting ./floci-data persists bucket contents, queue messages, or table rows across container restarts.
• Healthcheck – CI pipelines can