floci/floci-gcp repository overview

⁠floci-gcp

Light, fluffy, and always free — GCP Local Emulator No account. No auth token. No feature gates. Just docker run.

🌐 Website⁠ · 📖 Docs⁠ · 🐙 GitHub⁠

⁠What is floci-gcp?

floci-gcp is a free, open-source local emulator for Google Cloud Platform services, built for development, testing, and CI. Point your existing GCP SDK, gcloud CLI, Terraform, or test suite at http://localhost:4588 and keep your workflows intact — no cloud account, no service account key, no paid feature gates.

All GCP services (gRPC and REST) share a single port (4588) via HTTP/2 ALPN negotiation, so there's no per-service daemon setup or port juggling.

⁠Quick Start

⁠Docker

docker run -d --name floci-gcp \
  -p 4588:4588 \
  floci/floci-gcp:latest

⁠Docker Compose

services:
  floci-gcp:
    image: floci/floci-gcp:latest
    ports:
      - "4588:4588"
    volumes:
      - ./data:/app/data
    environment:
      FLOCI_GCP_HOSTNAME: floci-gcp
      FLOCI_GCP_BASE_URL: http://floci-gcp:4588

docker compose up -d

⁠Point your SDK at the emulator

export PUBSUB_EMULATOR_HOST=localhost:4588
export FIRESTORE_EMULATOR_HOST=localhost:4588
export DATASTORE_EMULATOR_HOST=localhost:4588
export STORAGE_EMULATOR_HOST=http://localhost:4588
export SECRET_MANAGER_EMULATOR_HOST=localhost:4588
export GOOGLE_CLOUD_PROJECT=floci-local

Credentials are not validated. Everything just works.

⁠Supported Services

⁠Image Tags

# Recommended for most users
image: floci/floci-gcp:latest

# Pinned release
image: floci/floci-gcp:1.0.0

# Bleeding edge
image: floci/floci-gcp:nightly

⁠Persistence Modes

Configure with FLOCI_GCP_STORAGE_MODE:

Mount a volume to /app/data (or set FLOCI_GCP_STORAGE_PERSISTENT_PATH) to retain data across container restarts.

⁠Configuration

All settings use the FLOCI_GCP_ prefix.

⁠Multi-container Docker Compose

When your application runs in another container, set FLOCI_GCP_HOSTNAME so URLs returned by the emulator resolve correctly between containers:

services:
  floci-gcp:
    image: floci/floci-gcp:latest
    ports:
      - "4588:4588"
    environment:
      FLOCI_GCP_HOSTNAME: floci-gcp
      FLOCI_GCP_BASE_URL: http://floci-gcp:4588

  my-app:
    image: my-app:latest
    environment:
      PUBSUB_EMULATOR_HOST: floci-gcp:4588
      FIRESTORE_EMULATOR_HOST: floci-gcp:4588
      STORAGE_EMULATOR_HOST: http://floci-gcp:4588
      SECRET_MANAGER_EMULATOR_HOST: floci-gcp:4588
    depends_on:
      - floci-gcp

⁠Health Check

The emulator exposes a health endpoint at /_floci/health on port 4588, suitable for Docker HEALTHCHECK directives, Kubernetes probes, and Testcontainers wait strategies.

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:4588/_floci/health"]
  interval: 10s
  timeout: 3s
  retries: 5

⁠Multi-Project Isolation

floci-gcp uses the GCP project ID as a multi-tenancy boundary — resources in project-a are invisible to project-b. The project ID is resolved from:

1. The URL path segment projects/{project}/...
2. The x-goog-request-params header
3. FLOCI_GCP_DEFAULT_PROJECT_ID (default: floci-local)

⁠Why floci-gcp?

GCP's official emulators are fragmented — each service ships its own binary, runs on a different port, and requires separate setup. floci-gcp unifies them.

⁠Links

• 📖 Documentation: floci.io/floci-gcp⁠
• 🐙 Source code: github.com/floci-io/floci-gcp⁠
• 🐛 Report an issue: github.com/floci-io/floci-gcp/issues⁠
• 💬 Contributing: CONTRIBUTING.md⁠

⁠License

Released under the MIT License⁠. Use it however you want.