Environment Variables Reference

floci-gcp is configured entirely through environment variables. Every setting maps to a FLOCI_GCP_* variable, so when you run the published Docker image you never need to write or mount an application.yml.

Variable names follow the config path, uppercased with dots and dashes replaced by underscores: e.g. floci-gcp.services.gcs.enabled becomes FLOCI_GCP_SERVICES_GCS_ENABLED.

Global

Variable	Default	Description
`FLOCI_GCP_PORT`	`4588`	Shared API port for gRPC and HTTP endpoints
`FLOCI_GCP_BASE_URL`	`http://localhost:4588`	Base URL embedded in service responses (GCS object URLs, pre-signed URLs, etc.)
`FLOCI_GCP_HOSTNAME`	(none)	Overrides only the hostname part of `FLOCI_GCP_BASE_URL`. Set to the Compose/container service name so other containers can reach floci-gcp by DNS
`FLOCI_GCP_DEFAULT_PROJECT_ID`	`floci-local`	Default GCP project ID used when no project is specified in the request
`FLOCI_GCP_MAX_REQUEST_SIZE`	`512`	Maximum request body size, in megabytes (applies to uploads, e.g. GCS objects)

TLS

Off by default: floci-gcp serves plain HTTP, which is what GCP SDKs expect from an emulator. When enabled, HTTP and HTTPS are served on the same port (FLOCI_GCP_PORT), so existing plain-HTTP clients keep working. See TLS / HTTPS for details.

Variable	Default	Description
`FLOCI_GCP_TLS_ENABLED`	`false`	Serve HTTPS alongside HTTP on the public port
`FLOCI_GCP_TLS_SELF_SIGNED`	`true`	Auto-generate a self-signed certificate when no cert/key is supplied. Stored under `FLOCI_GCP_STORAGE_PERSISTENT_PATH/tls/` and reused across restarts
`FLOCI_GCP_TLS_CERT_PATH`	(none)	PEM certificate file. Must be set together with the key path
`FLOCI_GCP_TLS_KEY_PATH`	(none)	PEM private key file
`FLOCI_GCP_TLS_HTTPS_PORT`	`443`	Extra port bound for HTTPS, since GCP SDKs assume HTTPS on 443 when no port is given. Set `0` to disable

Fetch the active certificate (over plain HTTP) with GET /_floci-gcp/tls-cert.

Storage

Variable	Default	Description
`FLOCI_GCP_STORAGE_MODE`	`memory`	Global storage backend: `memory`, `persistent`, `hybrid`, or `wal`
`FLOCI_GCP_STORAGE_PERSISTENT_PATH`	`./data`	Container-side directory for persistent and hybrid storage
`FLOCI_GCP_STORAGE_HOST_PERSISTENT_PATH`	`./data`	Host-side path that maps to the persistent directory. Used when floci-gcp spawns sidecar containers (Docker-in-Docker) that need to bind-mount the same data
`FLOCI_GCP_STORAGE_PRUNE_VOLUMES_ON_DELETE`	`false`	Remove the backing volume/data when a resource is deleted
`FLOCI_GCP_STORAGE_WAL_COMPACTION_INTERVAL_MS`	`30000`	How often (ms) WAL compaction runs. Only applies when `FLOCI_GCP_STORAGE_MODE=wal`

See Storage Modes for a full explanation of each mode.

DNS

floci-gcp's embedded DNS server runs inside the container and resolves GCS virtual-hosted style URLs to floci-gcp's container IP. It only activates when running inside Docker.

Built-in suffix	Covers
`localhost.floci.io`	`localhost.floci.io` and `*.localhost.floci.io` (e.g. `my-bucket.localhost.floci.io`)

Variable	Default	Description
`FLOCI_GCP_DNS_EXTRA_SUFFIXES`	(none)	Comma-separated list of additional hostname suffixes to resolve to floci-gcp's container IP
`FLOCI_GCP_DNS_CONTAINER_FALLBACK_ENABLED`	`true`	Append public resolvers after the embedded DNS in every spawned container so sidecars (Cloud Run, GKE, Kafka) can resolve public hostnames. Disable in offline or locked-down networks where these resolvers are blocked
`FLOCI_GCP_DNS_CONTAINER_FALLBACK_SERVERS`	`8.8.8.8,8.8.4.4`	The fallback resolvers appended when container fallback is enabled

Locations

See Locations.

Variable	Default	Description
`FLOCI_GCP_LOCATIONS_STRICT`	`false`	Reject unknown locations on regional create and list calls (Cloud Run resources, Cloud Functions, KMS, Cloud Tasks, Cloud Scheduler, Eventarc, Managed Kafka, GKE), and location combinations that cannot exist (such as a Cloud SQL `settings.locationPreference.zone` outside the instance region), with `INVALID_ARGUMENT`. Off by default: such requests are accepted as sent
`FLOCI_GCP_SERVICES_COMPUTE_REGIONS`	(unset)	Optional comma-separated Compute Engine region allow-list. Unset serves every catalog region with its real zones

Services

Each service can be toggled independently. All are enabled by default.

Variable	Default	Description
`FLOCI_GCP_SERVICES_GCS_ENABLED`	`true`	Cloud Storage (GCS)
`FLOCI_GCP_SERVICES_GCS_UPLOAD_SESSION_IDLE_TIMEOUT_SECONDS`	`604800`	Idle time before an unfinished resumable or streaming upload session is dropped (defaults to the real GCS seven-day session window)
`FLOCI_GCP_SERVICES_GCS_UPLOAD_SESSION_SWEEP_INTERVAL_SECONDS`	`3600`	How often abandoned upload sessions are swept; `0` disables the sweeper
`FLOCI_GCP_SERVICES_PUBSUB_ENABLED`	`true`	Pub/Sub
`FLOCI_GCP_SERVICES_FIRESTORE_ENABLED`	`true`	Firestore
`FLOCI_GCP_SERVICES_DATASTORE_ENABLED`	`true`	Datastore
`FLOCI_GCP_SERVICES_SECRETMANAGER_ENABLED`	`true`	Secret Manager
`FLOCI_GCP_SERVICES_IAM_ENABLED`	`true`	IAM
`FLOCI_GCP_SERVICES_IAM_AUTHORIZATION_MODE`	`disabled`	`enforce` evaluates stored policies for supported Resource Manager and GCS bucket/object operations. Default `disabled` keeps permissive behavior. Coverage and limits
`FLOCI_GCP_SERVICES_IAM_BOOTSTRAP_ADMIN_MEMBER`	unset	Optional IAM member granted `roles/storage.admin` on each newly created bucket
`FLOCI_GCP_SERVICES_IAMCREDENTIALS_ENABLED`	`true`	IAM Service Account Credentials (`generateAccessToken`)
`FLOCI_GCP_SERVICES_STS_ENABLED`	`true`	Security Token Service (STS)
`FLOCI_GCP_SERVICES_LOGGING_ENABLED`	`true`	Cloud Logging
`FLOCI_GCP_SERVICES_KMS_ENABLED`	`true`	Cloud KMS
`FLOCI_GCP_SERVICES_MONITORING_ENABLED`	`true`	Cloud Monitoring
`FLOCI_GCP_SERVICES_CLOUDTASKS_ENABLED`	`true`	Cloud Tasks
`FLOCI_GCP_SERVICES_SCHEDULER_ENABLED`	`true`	Cloud Scheduler
`FLOCI_GCP_SERVICES_SCHEDULER_INVOCATION_ENABLED`	`true`	Fire due Scheduler jobs in the background (disable for control plane only)
`FLOCI_GCP_SERVICES_SCHEDULER_TICK_INTERVAL_SECONDS`	`10`	How often the Scheduler background dispatcher checks for due jobs
`FLOCI_GCP_SERVICES_KAFKA_ENABLED`	`true`	Managed Service for Apache Kafka
`FLOCI_GCP_SERVICES_CLOUDSQL_ENABLED`	`true`	Cloud SQL for PostgreSQL
`FLOCI_GCP_SERVICES_CLOUDSQL_MOCK`	`false`	Mock mode: no Docker-backed PostgreSQL data-plane instances
`FLOCI_GCP_SERVICES_CLOUDRUN_ENABLED`	`true`	Cloud Run
`FLOCI_GCP_SERVICES_CLOUDRUN_MOCK`	`false`	Mock mode: control plane only, no Docker-backed execution containers
`FLOCI_GCP_SERVICES_CLOUDRUN_EXECUTION_DEFAULT_PORT`	`8080`	Default Cloud Run runtime container port
`FLOCI_GCP_SERVICES_CLOUDRUN_EXECUTION_STARTUP_TIMEOUT`	`240s`	Cloud Run runtime startup timeout
`FLOCI_GCP_SERVICES_CLOUDRUN_EXECUTION_REQUEST_TIMEOUT`	`300s`	Cloud Run invocation proxy timeout
`FLOCI_GCP_SERVICES_CLOUDRUN_EXECUTION_OPERATION_TIMEOUT`	`300s`	Maximum time for asynchronous Cloud Run execution operations before their LRO fails
`FLOCI_GCP_SERVICES_CLOUDRUN_EXECUTION_CLEANUP_TIMEOUT`	`15s`	Maximum time to wait for best-effort Docker cleanup after an operation is already resolved
`FLOCI_GCP_SERVICES_CLOUDRUN_EXECUTION_URL_HOST_SUFFIX`	`localhost.floci.io` or `FLOCI_GCP_HOSTNAME`	Host suffix used for generated Cloud Run execution URLs
`FLOCI_GCP_SERVICES_CLOUDRUN_EXECUTION_MAX_WORKER_INSTANCES`	`1`	Maximum replica containers run per Cloud Run worker pool; larger `manualInstanceCount` values are clamped with a warning
`FLOCI_GCP_SERVICES_CLOUDRUN_EXECUTION_SECURITY_OPTS`	unset	Comma-separated Docker security options for Cloud Run workload containers, for example `seccomp=unconfined`
`FLOCI_GCP_SERVICES_CLOUDFUNCTIONS_ENABLED`	`true`	Cloud Functions
`FLOCI_GCP_SERVICES_GKE_ENABLED`	`true`	GKE (Kubernetes Engine)
`FLOCI_GCP_SERVICES_BIGQUERY_ENABLED`	`true`	BigQuery
`FLOCI_GCP_SERVICES_BIGQUERY_MOCK`	`false`	Mock mode, runs queries on a built-in SQL subset instead of the DuckDB sidecar
`FLOCI_GCP_SERVICES_SERVICEUSAGE_ENABLED`	`true`	Service Usage
`FLOCI_GCP_SERVICES_SERVICEUSAGE_ENFORCEMENT_ENABLED`	`false`	Reject calls to APIs not enabled in the project with 403 `SERVICE_DISABLED` (see Service Usage)
`FLOCI_GCP_SERVICES_SERVICEUSAGE_DEFAULT_ENABLED`	GCP default set	Comma-separated APIs treated as enabled in every project until disabled; only used with enforcement
`FLOCI_GCP_SERVICES_RESOURCEMANAGER_ENABLED`	`true`	Cloud Resource Manager (minimal `projects.get`)
`FLOCI_GCP_SERVICES_FIREBASEAUTH_ENABLED`	`true`	Firebase Auth (Identity Platform)
`FLOCI_GCP_SERVICES_EVENTARC_ENABLED`	`true`	Eventarc

Sidecar containers

Some services (e.g. Managed Kafka) start real sidecar containers via the host Docker daemon. These variables control how those containers are networked.

Variable	Default	Description
`FLOCI_GCP_SERVICES_DOCKER_NETWORK`	(none)	Shared Docker network attached to spawned sidecar containers so floci-gcp and your SDKs can reach them by name. Set this to your Compose/CI network
`FLOCI_GCP_DOCKER_RESOURCE_NAMESPACE`	–	Namespace inserted into sidecar container/volume names (`floci-gcp-<ns>-…`) so parallel emulator instances on one Docker host don't collide

Managed Kafka

Variable	Default	Description
`FLOCI_GCP_SERVICES_KAFKA_MOCK`	`false`	When `true`, emulate the Kafka control plane only: no Redpanda broker container is started
`FLOCI_GCP_SERVICES_KAFKA_DEFAULT_IMAGE`	`redpandadata/redpanda:latest`	Broker image used for spawned Kafka clusters
`FLOCI_GCP_SERVICES_KAFKA_DOCKER_NETWORK`	(none)	Overrides `FLOCI_GCP_SERVICES_DOCKER_NETWORK` for Kafka sidecars only

Cloud SQL for PostgreSQL

Variable	Default	Description
`FLOCI_GCP_SERVICES_CLOUDSQL_MOCK`	`false`	When `true`, emulate the Cloud SQL control plane only: no Docker-backed PostgreSQL containers are started
`FLOCI_GCP_SERVICES_CLOUDSQL_POSTGRES15_IMAGE`	`postgres:15.18-alpine`	Docker image used for `POSTGRES_15` instances
`FLOCI_GCP_SERVICES_CLOUDSQL_POSTGRES16_IMAGE`	`postgres:16.14-alpine`	Docker image used for `POSTGRES_16` instances
`FLOCI_GCP_SERVICES_CLOUDSQL_POSTGRES17_IMAGE`	`postgres:17.10-alpine`	Docker image used for `POSTGRES_17` instances
`FLOCI_GCP_SERVICES_CLOUDSQL_POSTGRES18_IMAGE`	`postgres:18.4-alpine`	Docker image used for `POSTGRES_18` instances
`FLOCI_GCP_SERVICES_CLOUDSQL_MYSQL80_IMAGE`	`mysql:8.0.46`	Docker image used for `MYSQL_8_0` and `MYSQL_8_0_NN` instances
`FLOCI_GCP_SERVICES_CLOUDSQL_MYSQL84_IMAGE`	`mysql:8.4.11`	Docker image used for `MYSQL_8_4` instances
`FLOCI_GCP_SERVICES_CLOUDSQL_STARTUP_TIMEOUT_SECONDS`	`90`	Max time to wait for PostgreSQL readiness after container start

BigQuery

Variable	Default	Description
`FLOCI_GCP_SERVICES_BIGQUERY_MOCK`	`false`	When `true`, queries run on a built-in SQL subset and no floci-duck container is started
`FLOCI_GCP_SERVICES_BIGQUERY_DUCK_DEFAULT_IMAGE`	`floci/floci-duck:latest`	Image of the DuckDB sidecar that executes GoogleSQL queries
`FLOCI_GCP_SERVICES_BIGQUERY_DUCK_URL`	(none)	Use an already running floci-duck at this URL instead of starting a container
`FLOCI_GCP_SERVICES_BIGQUERY_DUCK_CALLBACK_URL`	(derived)	Base URL the sidecar reads staged rows back from. Only needed when `DUCK_URL` points at a sidecar that cannot reach floci-gcp through the resolved docker host
`FLOCI_GCP_SERVICES_BIGQUERY_UPLOAD_SESSION_IDLE_TIMEOUT_SECONDS`	`604800`	Idle time before an unfinished resumable media upload for a load job is dropped (defaults to the seven-day resumable upload window)
`FLOCI_GCP_SERVICES_BIGQUERY_UPLOAD_SESSION_SWEEP_INTERVAL_SECONDS`	`3600`	Interval between sweeps for expired BigQuery upload sessions; `0` disables the sweeper

GKE (Kubernetes Engine)

Variable	Default	Description
`FLOCI_GCP_SERVICES_GKE_MOCK`	`false`	When `true`, emulate the GKE control plane only: no real `k3s` clusters are started
`FLOCI_GCP_SERVICES_GKE_DEFAULT_IMAGE`	`rancher/k3s:latest`	Image used for spawned k3s control-plane containers
`FLOCI_GCP_SERVICES_GKE_API_SERVER_BASE_PORT`	`6550`	Lowest host port assigned to a cluster's Kubernetes API server
`FLOCI_GCP_SERVICES_GKE_API_SERVER_MAX_PORT`	`6599`	Highest host port assigned to a cluster's Kubernetes API server
`FLOCI_GCP_SERVICES_GKE_KEEP_RUNNING_ON_SHUTDOWN`	`false`	When `true`, leave spawned k3s containers running after floci-gcp shuts down
`FLOCI_GCP_SERVICES_GKE_ENDPOINT_MODE`	`host`	How the cluster endpoint is advertised to `kubectl`: `host` (a reachable `host:port`) or `network` (the container's network address, for emulator-in-Docker setups)
`FLOCI_GCP_SERVICES_GKE_DOCKER_NETWORK`	(none)	Overrides `FLOCI_GCP_SERVICES_DOCKER_NETWORK` for GKE/k3s sidecars only

Initialization Hooks

Control the shell environment used to run initialization hook scripts.

Variable	Default	Description
`FLOCI_GCP_INIT_HOOKS_SHELL_EXECUTABLE`	`/bin/sh`	Shell used to execute init hook scripts
`FLOCI_GCP_INIT_HOOKS_TIMEOUT_SECONDS`	`30`	Max time a single hook may run before it is killed
`FLOCI_GCP_INIT_HOOKS_SHUTDOWN_GRACE_PERIOD_SECONDS`	`2`	Grace period given to hook processes on shutdown

Docker Daemon

These variables control the Docker daemon used by floci-gcp's embedded DNS and sidecar container management.

Variable	Default	Description
`FLOCI_GCP_DOCKER_DOCKER_HOST`	`unix:///var/run/docker.sock`	Docker daemon socket path or TCP address
`FLOCI_GCP_DOCKER_DOCKER_CONFIG_PATH`	(none)	Path to a directory containing Docker's `config.json` for registry auth
`FLOCI_GCP_DOCKER_API_TIMEOUT`	`30s`	Per-call Docker API timeout before floci-gcp resets the Docker client
`FLOCI_GCP_DOCKER_LOG_MAX_SIZE`	`10m`	Log rotation max size for spawned containers
`FLOCI_GCP_DOCKER_LOG_MAX_FILE`	`3`	Number of rotated log files to keep
`FLOCI_GCP_DOCKER_IMAGE_REGISTRY_BASE`	(none)	Registry prefix applied to every sidecar image floci-gcp launches (e.g. an internal mirror like `mirror.example.com`)

Private-registry credentials (floci-gcp.docker.registry-credentials, a list of server/username/password entries) are best set in an application.yml: see the application.yml reference.

Logging

floci-gcp uses standard Quarkus logging, which is also driven by environment variables. The default level is INFO; services log operation-level events at DEBUG and full request/response payloads at TRACE.

Enable TRACE for a single service by setting its category level (note the double underscores around the category):

# Pub/Sub: log publish/pull bodies
QUARKUS_LOG_CATEGORY__IO_FLOCI_GCP_SERVICES_PUBSUB__LEVEL=TRACE

# Firestore: log read/write operations
QUARKUS_LOG_CATEGORY__IO_FLOCI_GCP_SERVICES_FIRESTORE__LEVEL=TRACE

Set the global level with QUARKUS_LOG_LEVEL (e.g. QUARKUS_LOG_LEVEL=DEBUG).