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 Server containers are started on-demand when a server is created via the management API. The Docker socket mount is required:

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_ACCEPT_EULA: "Y"   # accept the Microsoft SQL Server EULA
      # FLOCI_AZ_SERVICES_SQL_IMAGE: "mcr.microsoft.com/azure-sql-edge: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).

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/KBHBeksoGMh0==;
        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`	`dev` — accept any credentials; `strict` — validate HMAC-SHA256 signatures

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

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_ACCEPT_EULA`	(empty)	Set to `Y` to accept the Microsoft SQL Server EULA (required)
`FLOCI_AZ_SERVICES_SQL_IMAGE`	`mcr.microsoft.com/azure-sql-edge: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_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

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

floci-az exposes a health endpoint you can use in depends_on conditions:

services:
  floci-az:
    image: floci/floci-az:latest
    ports:
      - "4577:4577"
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:4577/health"]
      interval: 5s
      timeout: 3s
      retries: 5

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