Skip to content

Docker Compose Configuration

Most users configure floci-az entirely through environment variables: no config files needed. Every floci-az.* setting maps to a FLOCI_AZ_* env var (replace . with _, uppercase).


Common Scenarios

Storage only (no Functions)

The simplest setup: skips the Docker socket mount entirely:

services:
  floci-az:
    image: floci/floci-az:latest
    ports:
      - "4577:4577"
    environment:
      FLOCI_AZ_SERVICES_FUNCTIONS_ENABLED: "false"

All services (default)

services:
  floci-az:
    image: floci/floci-az:latest
    ports:
      - "4577:4577"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock  # required for Azure Functions

With persistent storage

Data survives container restarts. Mount a local directory and set a storage mode:

services:
  floci-az:
    image: floci/floci-az:latest
    ports:
      - "4577:4577"
    volumes:
      - ./data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      FLOCI_AZ_STORAGE_MODE: hybrid        # in-memory + async flush every 5 s (recommended)
      # FLOCI_AZ_STORAGE_MODE: wal         # every write goes to disk before responding
      # FLOCI_AZ_STORAGE_MODE: persistent  # flush only on graceful shutdown

With Azure SQL Database

SQL defaults to control-plane-only mode and needs no Docker socket. To opt into managed SQL Server containers, set the provider to managed, accept the EULA, and mount the Docker socket:

services:
  floci-az:
    image: floci/floci-az:latest
    ports:
      - "4577:4577"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      FLOCI_AZ_SERVICES_SQL_DATA_PLANE_PROVIDER: managed
      FLOCI_AZ_SERVICES_SQL_ACCEPT_EULA: "Y"   # accept the Microsoft SQL Server EULA
      # FLOCI_AZ_SERVICES_SQL_IMAGE: "mcr.microsoft.com/mssql/server:2025-latest"

SQL Server containers bind a random host port directly via Docker: do not add those ports to the floci-az service's ports: block. Use the /connect endpoint to discover the port.

CI / Ephemeral: maximum speed

Pure in-memory, no socket required, fastest startup:

services:
  floci-az:
    image: floci/floci-az:latest
    ports:
      - "4577:4577"
    environment:
      FLOCI_AZ_STORAGE_MODE: memory
      FLOCI_AZ_SERVICES_FUNCTIONS_ENABLED: "false"

Selective services

Disable services you don't use:

services:
  floci-az:
    image: floci/floci-az:latest
    ports:
      - "4577:4577"
    environment:
      FLOCI_AZ_SERVICES_BLOB_ENABLED: "true"
      FLOCI_AZ_SERVICES_QUEUE_ENABLED: "true"
      FLOCI_AZ_SERVICES_TABLE_ENABLED: "false"
      FLOCI_AZ_SERVICES_FUNCTIONS_ENABLED: "false"
      FLOCI_AZ_SERVICES_APP_CONFIG_ENABLED: "false"

Per-service storage override

Run most services in-memory, but use WAL for blob durability:

services:
  floci-az:
    image: floci/floci-az:latest
    ports:
      - "4577:4577"
    volumes:
      - ./data:/app/data
    environment:
      FLOCI_AZ_STORAGE_MODE: memory
      FLOCI_AZ_STORAGE_SERVICES_BLOB_MODE: wal

With Docker-backed engines (Cosmos MongoDB, Event Hubs…)

Docker-backed engines (Cosmos MongoDB/PostgreSQL/Cassandra/Gremlin) and Event Hubs sidecars (Artemis, Redpanda) are launched as sibling containers by floci-az via the Docker socket. They bind their ports directly on the host; do not publish those ports on the floci-az service:

services:
  floci-az:
    image: floci/floci-az:latest
    ports:
      - "4577:4577"
      - "4578:4578"   # Cosmos DB: Java SDK (HTTPS)
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      # Cosmos engines
      FLOCI_AZ_SERVICES_COSMOS_ENGINES_MONGODB_ENABLED: "true"
      FLOCI_AZ_SERVICES_COSMOS_ENGINES_POSTGRESQL_ENABLED: "true"
      # Event Hubs
      FLOCI_AZ_SERVICES_EVENT_HUB_ENABLED: "true"

Once the sidecars start, their ports are available on the host: localhost:27017 (MongoDB), localhost:5432 (PostgreSQL), localhost:5672 (AMQP / Artemis).

Sidecars and Docker networks

Docker Compose puts its services on a user-defined network, where containers resolve each other by name. A plain docker run without --network puts floci-az on Docker's default bridge network instead, which does not resolve container names. floci-az still reaches its sidecars there by container IP, so Redis caches, container registries and database servers finish provisioning, but the host names it reports for Redis, PostgreSQL, MySQL, MariaDB and SQL Server are container names that clients on the default bridge cannot resolve. floci-az logs a warning at startup in that case. Use a user-defined network:

docker network create floci-net
docker run -d --name floci-az --network floci-net -p 4577:4577 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e FLOCI_AZ_SERVICES_DOCKER_NETWORK=floci-net \
  floci/floci-az:latest

With the Azure CLI inside the container

Use the latest-compat image when your scripts need Azure tooling inside the container. It includes the Azure CLI and azfloci. Call azfloci to target the local emulator without passing a connection string; plain az still needs explicit connection settings. See Docker Images for what the compat image contains.

services:
  floci-az:
    image: floci/floci-az:latest-compat
    ports:
      - "4577:4577"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Multi-container (your app + floci-az)

When your application also runs in Docker, use the service name as the hostname:

services:
  floci-az:
    image: floci/floci-az:latest
    ports:
      - "4577:4577"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - app-net

  my-app:
    image: my-app:latest
    environment:
      AZURE_STORAGE_CONNECTION_STRING: >-
        DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;
        AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;
        BlobEndpoint=http://floci-az:4577/devstoreaccount1;
        QueueEndpoint=http://floci-az:4577/devstoreaccount1-queue;
        TableEndpoint=http://floci-az:4577/devstoreaccount1-table;
      # App Configuration: https:// required by the SDK; use ForceHttp transport in your client
      AZURE_APPCONFIG_ENDPOINT: https://floci-az:4577/devstoreaccount1-appconfig
    depends_on:
      - floci-az
    networks:
      - app-net

networks:
  app-net:

Environment Variable Reference

All variables are optional; the default applies when unset.

Core

Variable Default Description
FLOCI_AZ_PORT 4577 Port the emulator listens on
FLOCI_AZ_BASE_URL http://localhost:4577 Base URL embedded in API responses
FLOCI_AZ_HOSTNAME (unset) Override the hostname in SAS and invoke URLs (useful behind a reverse proxy)
FLOCI_AZ_AUTH_MODE dev Not enforced yet: every value, strict included, accepts any credentials without validating SharedKey signatures. Blob service SAS signatures are checked against auth.storage-account-keys regardless
FLOCI_AZ_PARITY compat Azure parity level. compat: responses stay as floci-az has always answered them. azure: every parity override on. strict: azure plus Azure's refusals. See the ARM page
FLOCI_AZ_PARITY_OVERRIDES_SUBSCRIPTION_LISTING (on from azure) true: GET /subscriptions also lists subscriptions registered on first use, and a subscription is echoed with the directory's id
FLOCI_AZ_PARITY_OVERRIDES_STRICT_SUBSCRIPTIONS (on from strict) true: an unknown subscription is 404 SubscriptionNotFound; false: it is registered on first use
FLOCI_AZ_PARITY_OVERRIDES_RESOURCE_GROUP_SEMANTICS (on from azure) true: a resource-group re-PUT answers 200, a resource PUT under a missing group creates the group, and groups persist in the directory store
FLOCI_AZ_PARITY_OVERRIDES_RESOURCE_GROUP_DELETE (on from azure) true: a resource-group DELETE deletes every resource in the group and answers 202 with a Location to poll; false: 200, only the group is removed
FLOCI_AZ_PARITY_OVERRIDES_STRICT_RESOURCE_GROUPS (on from strict) true: a request for a resource under a group that does not exist is 404 ResourceGroupNotFound, and groups persist in the directory store
FLOCI_AZ_CLOUD_DEFAULT AzureCloud Cloud of the default tenant: AzureCloud, AzureUSGovernment or AzureChinaCloud

Storage

Variable Default Description
FLOCI_AZ_STORAGE_MODE memory Global storage backend: memory · persistent · hybrid · wal
FLOCI_AZ_STORAGE_PERSISTENT_PATH /app/data Container-side directory for persisted state
FLOCI_AZ_STORAGE_HOST_PERSISTENT_PATH (same as above) Host-side path when running Docker-in-Docker
FLOCI_AZ_STORAGE_WAL_COMPACTION_INTERVAL_MS 30000 How often the WAL is compacted (ms)
FLOCI_AZ_STORAGE_HYBRID_FLUSH_INTERVAL_MS 5000 How often hybrid mode flushes to disk (ms)

Per-service storage overrides

Variable Default Description
FLOCI_AZ_STORAGE_SERVICES_BLOB_MODE (global) Storage mode for Blob Storage only
FLOCI_AZ_STORAGE_SERVICES_QUEUE_MODE (global) Storage mode for Queue Storage only
FLOCI_AZ_STORAGE_SERVICES_TABLE_MODE (global) Storage mode for Table Storage only
FLOCI_AZ_STORAGE_SERVICES_APP_CONFIG_MODE (global) Storage mode for App Configuration only
FLOCI_AZ_STORAGE_SERVICES_DIRECTORY_MODE (global) Storage mode for the ARM tenant and subscription directory only

Enable / disable services

Variable Default Description
FLOCI_AZ_SERVICES_BLOB_ENABLED true Enable or disable Blob Storage
FLOCI_AZ_SERVICES_QUEUE_ENABLED true Enable or disable Queue Storage
FLOCI_AZ_SERVICES_TABLE_ENABLED true Enable or disable Table Storage
FLOCI_AZ_SERVICES_FUNCTIONS_ENABLED true Enable or disable Azure Functions
FLOCI_AZ_SERVICES_APP_CONFIG_ENABLED true Enable or disable App Configuration
FLOCI_AZ_SERVICES_COSMOS_ENABLED true Enable or disable Cosmos DB (SQL API)
FLOCI_AZ_SERVICES_KEY_VAULT_ENABLED true Enable or disable Key Vault
FLOCI_AZ_SERVICES_EVENT_HUB_ENABLED true Enable or disable Event Hubs
FLOCI_AZ_SERVICES_SQL_ENABLED true Enable or disable Azure SQL Database

Azure SQL Database

Variable Default Description
FLOCI_AZ_SERVICES_SQL_DATA_PLANE_PROVIDER none none for ARM state only; managed for a real SQL Server container; external is reserved
FLOCI_AZ_SERVICES_SQL_MOCKED (unset) Deprecated provider alias: true = none, false = managed
FLOCI_AZ_SERVICES_SQL_ACCEPT_EULA N Set to Y to accept the Microsoft SQL Server EULA (managed mode only)
FLOCI_AZ_SERVICES_SQL_IMAGE mcr.microsoft.com/mssql/server:2025-latest Docker image for SQL Server containers
FLOCI_AZ_SERVICES_SQL_STARTUP_TIMEOUT_SECONDS 60 Seconds to wait for SQL Server to become ready

Azure Functions

Variable Default Description
FLOCI_AZ_SERVICES_FUNCTIONS_EPHEMERAL false true: fresh container per invocation; false: reuse warm containers
FLOCI_AZ_SERVICES_FUNCTIONS_CONTAINER_IDLE_TIMEOUT_SECONDS 300 Evict warm containers idle longer than this; 0 disables eviction
FLOCI_AZ_SERVICES_FUNCTIONS_CODE_PATH ~/.floci-az/functions Where extracted function code is stored on the host
FLOCI_AZ_SERVICES_FUNCTIONS_DOCKER_HOST_OVERRIDE (unset) Override the hostname function containers use to reach floci-az

Docker daemon

Variable Default Description
FLOCI_AZ_DOCKER_DOCKER_HOST unix:///var/run/docker.sock Docker daemon socket, unix socket or tcp://host:port
FLOCI_AZ_DOCKER_ENDPOINT_MODE auto How sidecar containers are addressed, by floci-az and in the host/port reported to clients. auto: container name/IP and internal port when floci-az runs in a container, localhost and the published port otherwise. published: always the Docker daemon's host (from docker-host) and the published port. Use it for remote daemons such as docker-in-docker or kubedock, whose containers aren't directly reachable
FLOCI_AZ_SERVICES_DOCKER_NETWORK (detected) Docker network sidecar containers join. Defaults to the network floci-az itself runs on, preferring a user-defined one. On the default bridge network floci-az reaches sidecars by container IP
FLOCI_AZ_DOCKER_LOG_MAX_SIZE 10m Max log file size per function container
FLOCI_AZ_DOCKER_LOG_MAX_FILE 3 Max rotated log files per function container
FLOCI_AZ_DOCKER_DOCKER_CONFIG_PATH (unset) Path to Docker config.json for private registry auth
FLOCI_AZ_DOCKER_RESOURCE_NAMESPACE (unset) Namespace inserted into the name of every container and volume floci-az creates (floci-az-<ns>-...) and added as the floci_namespace label, so parallel emulator instances on one Docker host don't collide

Web console

Variable Default Description
FLOCI_AZ_UI_ENABLED true Allow /_floci/ui to start the web console
FLOCI_AZ_UI_IMAGE floci/floci-ui:0.7.0 Console image
FLOCI_AZ_UI_PORT 4500 Host port the console is published on. No ports: entry needed
FLOCI_AZ_UI_ENDPOINT (derived) URL the console uses to reach floci-az

Resource Identity Labels

Every container and volume floci-az creates carries the base labels floci=true, floci_emulator=floci-az and, when FLOCI_AZ_DOCKER_RESOURCE_NAMESPACE is set, floci_namespace. A container backing an emulated Azure resource also carries labels tying it back to that resource, additive to the base labels:

Label Value Purpose
io.floci az Cloud provider, for multi-cloud discovery when several Floci emulators share a host
io.floci.service e.g. postgres The Azure service the container backs
io.floci.resource-id e.g. orders-db The Azure resource name (server, cache, cluster, VM, container group, container app, namespace, function app)
io.floci.subscription the subscription id The subscription the resource belongs to
io.floci.resource-group the resource group name The resource group the resource belongs to
io.floci.location e.g. eastus The Azure location of the resource
floci_service same as io.floci.service Legacy: still written, prefer the new key

This makes docker ps --filter label=io.floci.service=postgres --filter label=io.floci.resource-id=orders-db resolve an emulated resource to its backing container directly. A label whose value is unknown is omitted rather than written empty.

Labels are written when a container is created, so they apply to containers floci-az starts after upgrading. A container that already existed keeps the labels it was created with (typically only the base labels and floci_service) until floci-az recreates it, for example when the resource is deleted and created again.

  • All six keys: Azure Cache for Redis, Azure Database for PostgreSQL, MySQL and MariaDB, Azure SQL Database, AKS, Virtual Machines, Container Instances and Container Apps.
  • No scope keys (io.floci.subscription, io.floci.resource-group, io.floci.location): Service Bus and Event Hubs namespaces and Azure Functions apps, whose data-plane APIs carry no Azure scope.
  • No io.floci.resource-id and no scope keys: the shared ACR registry, the Event Hubs Kafka (Redpanda) sidecar and the per-API Cosmos DB engine containers, which are singletons with no single resource behind them.

io.floci, io.floci.service and io.floci.resource-id follow the keys floci-aws uses, so a host running both emulators can filter their containers the same way; each emulator adds its own scope keys (io.floci.account and io.floci.region there, the subscription, resource group and location keys here). floci-gcp and floci-oci do not write these keys yet.


Docker Socket Access

The Docker socket mount (/var/run/docker.sock) is required for Azure Functions. The container entrypoint automatically detects the socket's group ID at runtime and adjusts permissions: this works on both Docker Desktop (macOS/Windows) and native Linux Docker with no manual configuration.

If you don't need Functions, omit the socket mount and set FLOCI_AZ_SERVICES_FUNCTIONS_ENABLED=false.


Health Check

The published image ships its own probe, /usr/local/bin/healthcheck.sh, and declares it as the image HEALTHCHECK, so depends_on with condition: service_healthy works without a healthcheck: block. The image has neither curl nor wget, so an override that calls either never passes. To tune the timings, point the override at the same script:

services:
  floci-az:
    image: floci/floci-az:latest
    ports:
      - "4577:4577"
    healthcheck:
      test: ["CMD", "healthcheck.sh"]
      interval: 5s
      timeout: 3s
      retries: 10

  my-app:
    depends_on:
      floci-az:
        condition: service_healthy

The script sends GET /_floci/health and passes on a 200. The endpoint answers:

{"status": "UP", "version": "0.14.0", "edition": "floci-az-always-free"}
Field Meaning
status UP, or DOWN with a 503 and a problems map when a service reports a problem
version The floci-az release the image was built from (FLOCI_AZ_VERSION), or dev for a local build
edition Always floci-az-always-free

GET /health returns the same body. See Emulator Endpoints for the other control-plane paths, including POST /_admin/reset.

/ready is the readiness probe: it answers 503 with {"status":"DOWN"} until every service has finished its startup work (for example Service Bus start-on-boot or eager Cosmos engines) and again once shutdown begins. In between it answers what /health (also served at /_floci/health) answers: 200 with {"status":"UP"}, or 503 when a service reports a problem. /health does not wait for startup to finish.