Deploy Floci — GCP Emulator

Deploy and Host Floci GCP Emulator on Railway

Floci GCP is a fast, free, and open-source Google Cloud Platform emulator for development, testing, automation, and CI/CD workflows.

It provides GCP-compatible REST and gRPC APIs through a single endpoint, allowing applications to use services such as Cloud Storage, Pub/Sub, Firestore, Datastore, Secret Manager, IAM, KMS, Cloud Tasks, Cloud Scheduler, BigQuery, Cloud Run, Cloud SQL, GKE, and more without requiring a real Google Cloud account.

About Hosting Floci GCP

This template deploys Floci GCP on Railway using the official floci/floci-gcp:latest Docker image.

All supported GCP REST and gRPC services share a unified endpoint on port 4588. Applications, Google Cloud SDKs, development environments, Terraform, OpenTofu, and automated test suites can connect to the Railway deployment instead of real GCP endpoints.

Persistent emulator state is stored in a Railway volume mounted at /app/data.

Some advanced Floci GCP services normally start Docker sidecars, including Cloud Run, Cloud SQL, Managed Kafka, and GKE. Railway does not expose the host Docker socket, so this template configures those services to use their mock implementations instead.

Common Use Cases

• Develop applications against GCP-compatible APIs without a Google Cloud account
• Test Cloud Storage, Pub/Sub, Firestore, Datastore, Secret Manager, and other GCP services
• Run integration and end-to-end tests against isolated GCP-like infrastructure
• Test Google Cloud SDK integrations
• Use Terraform or OpenTofu against emulated GCP APIs
• Build CI/CD environments without consuming real GCP resources
• Test middleware and automation workflows that integrate with GCP
• Provide a shared remote GCP emulator for development teams

Dependencies for Floci GCP Hosting

• Official floci/floci-gcp:latest Docker image
• Railway public networking on port 4588
• Railway persistent volume mounted at /app/data

How to Use Floci GCP

After deployment, Railway provides a public domain similar to:

https://your-floci-gcp.up.railway.app

Use this Railway domain as your GCP emulator endpoint.

For the examples below:

export FLOCI_GCP_ENDPOINT="https://your-floci-gcp.up.railway.app"
export GOOGLE_CLOUD_PROJECT="floci-local"

Replace the example URL with your actual Railway public domain.

1. Check Floci GCP Health

Verify that the emulator is running:

curl "$FLOCI_GCP_ENDPOINT/_floci-gcp/health"

The Floci GCP control plane is available under:

/_floci-gcp

2. Configure GCP Emulator Variables

Google Cloud SDK libraries support standard emulator environment variables.

Point them to your Railway deployment:

export GOOGLE_CLOUD_PROJECT="floci-local"

export PUBSUB_EMULATOR_HOST="your-floci-gcp.up.railway.app:443"
export FIRESTORE_EMULATOR_HOST="your-floci-gcp.up.railway.app:443"
export DATASTORE_EMULATOR_HOST="your-floci-gcp.up.railway.app:443"
export SECRET_MANAGER_EMULATOR_HOST="your-floci-gcp.up.railway.app:443"

export STORAGE_EMULATOR_HOST="https://your-floci-gcp.up.railway.app"

Floci does not require a real Google Cloud account or real production credentials for normal emulator usage.

3. Cloud Storage Example

Using Python and google-cloud-storage:

import os
from google.cloud import storage

os.environ["STORAGE_EMULATOR_HOST"] = (
    "https://your-floci-gcp.up.railway.app"
)

client = storage.Client(project="floci-local")

bucket = client.bucket("my-bucket")
client.create_bucket(bucket)

blob = bucket.blob("hello.txt")
blob.upload_from_string("Hello from Floci GCP on Railway")

print(blob.download_as_text())

This creates the bucket and object inside Floci instead of real Google Cloud Storage.

4. Pub/Sub Example

Configure the emulator:

export PUBSUB_EMULATOR_HOST="your-floci-gcp.up.railway.app:443"
export GOOGLE_CLOUD_PROJECT="floci-local"

Using Python:

import os

os.environ["PUBSUB_EMULATOR_HOST"] = (
    "your-floci-gcp.up.railway.app:443"
)

from google.cloud import pubsub_v1

publisher = pubsub_v1.PublisherClient()

topic_path = publisher.topic_path(
    "floci-local",
    "events"
)

publisher.create_topic(
    request={"name": topic_path}
)

future = publisher.publish(
    topic_path,
    b"hello from floci-gcp"
)

future.result()

5. Firestore Example

Configure Firestore:

export FIRESTORE_EMULATOR_HOST="your-floci-gcp.up.railway.app:443"
export GOOGLE_CLOUD_PROJECT="floci-local"

Using Python:

import os

os.environ["FIRESTORE_EMULATOR_HOST"] = (
    "your-floci-gcp.up.railway.app:443"
)

from google.cloud import firestore

db = firestore.Client(
    project="floci-local"
)

db.collection("users").document("1").set({
    "name": "Floci User",
    "environment": "Railway"
})

document = (
    db.collection("users")
    .document("1")
    .get()
)

print(document.to_dict())

Supported GCP Services

Floci GCP provides emulation for a broad range of Google Cloud APIs, including:

• Cloud Storage
• Pub/Sub
• Firestore
• Datastore
• Secret Manager
• Cloud KMS
• IAM
• IAM Service Account Credentials
• STS
• OAuth
• Firebase Authentication
• Cloud Logging
• Cloud Monitoring
• Cloud Tasks
• Cloud Scheduler
• Eventarc
• BigQuery
• Cloud Functions
• Cloud Run
• Cloud SQL
• Managed Kafka
• Google Kubernetes Engine
• Resource Manager
• Service Usage

Service coverage and implementation completeness may vary between releases.

Docker-Backed Services on Railway

Some Floci GCP services can normally start additional Docker containers.

These include:

Railway does not expose:

/var/run/docker.sock

Therefore this template uses:

FLOCI_GCP_SERVICES_KAFKA_MOCK="true"
FLOCI_GCP_SERVICES_CLOUDSQL_MOCK="true"
FLOCI_GCP_SERVICES_CLOUDRUN_MOCK="true"
FLOCI_GCP_SERVICES_GKE_MOCK="true"

This allows control-plane and API-level emulation without requiring Docker sidecars.

Persistent Storage

This template uses:

FLOCI_GCP_STORAGE_MODE="persistent"
FLOCI_GCP_STORAGE_PERSISTENT_PATH="/app/data"

with a Railway volume mounted at:

/app/data

In persistent mode, writes are persisted directly to disk.

Floci GCP also supports other storage modes such as:

This Railway template uses persistent to provide predictable state retention across restarts.

Deleting the Railway volume will also delete the persisted emulator state.

Floci GCP vs Official GCP Emulators

Google's official emulators are generally deployed as separate service-specific processes, while Floci GCP provides multiple GCP-compatible services through a single endpoint.

Why Deploy Floci GCP on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

Deploying Floci GCP on Railway provides a remotely accessible GCP-compatible development environment with automatic HTTPS, persistent storage, unified REST and gRPC endpoints, and simple infrastructure management without maintaining your own server.