Docker Configuration

Floci spawns real Docker containers for services that need them: Lambda, RDS, ElastiCache, OpenSearch, MSK, and ECS. All of these share the same Docker client configuration, controlled under floci.docker.

Docker Daemon Socket

By default Floci connects to the local Docker daemon via the Unix socket. Override it with docker-host when needed (e.g. a remote Docker host or a non-standard socket path):

floci:
  docker:
    docker-host: unix:///var/run/docker.sock

Running natively on Windows (not inside WSL or a container): Windows has no equivalent of /var/run/docker.sock, so when docker-host is left at its default and DOCKER_HOST isn't set, Floci automatically falls back to Docker Desktop's named pipe (npipe:////./pipe/docker_engine) instead. An explicit docker-host or DOCKER_HOST always takes priority over this fallback.

Environment variable: FLOCI_DOCKER_DOCKER_HOST

When running Floci inside Docker Compose, mount the host socket:

services:
  floci:
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

The container normally switches to the unprivileged floci user (UID 1001), including when started with --user root. If the mounted socket is accessible only to root, set the entrypoint option FLOCI_RUN_AS_ROOT=true to keep Floci running as root:

docker run --rm -p 4566:4566 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e FLOCI_RUN_AS_ROOT=true \
  floci/floci:latest

In Docker Compose, use the same environment variable:

services:
  floci:
    image: floci/floci:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      FLOCI_RUN_AS_ROOT: "true"

Use this only when the socket's permissions require root. Without the option, Floci retains its unprivileged default. The setting applies to the container entrypoint, not to floci.docker configuration.

Private Registry Authentication

Any service that pulls a container image from a private registry (Lambda image functions, custom OpenSearch images, private Postgres images, etc.) needs Docker credentials. Two approaches are supported and can be combined.

Mount the host Docker config

Reuses existing docker login sessions and credential helpers from the host machine. Mount the host ~/.docker directory and point Floci at it:

services:
  floci:
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ~/.docker:/root/.docker:ro
    environment:
      FLOCI_DOCKER_DOCKER_CONFIG_PATH: /root/.docker

Or in application.yml:

floci:
  docker:
    docker-config-path: /root/.docker

This works with any credential helper configured on the host (docker-credential-desktop, ecr-credential-helper, etc.) as long as the helper binary is also available inside the Floci container.

Explicit per-registry credentials

For CI environments or air-gapped setups where mounting the host filesystem is not practical:

services:
  floci:
    environment:
      FLOCI_DOCKER_REGISTRY_CREDENTIALS_0__SERVER: myregistry.example.com
      FLOCI_DOCKER_REGISTRY_CREDENTIALS_0__USERNAME: myuser
      FLOCI_DOCKER_REGISTRY_CREDENTIALS_0__PASSWORD: mypassword
      # Add more registries by incrementing the index:
      # FLOCI_DOCKER_REGISTRY_CREDENTIALS_1__SERVER: other.registry.io
      # FLOCI_DOCKER_REGISTRY_CREDENTIALS_1__USERNAME: ...
      # FLOCI_DOCKER_REGISTRY_CREDENTIALS_1__PASSWORD: ...

Or in application.yml:

floci:
  docker:
    registry-credentials:
      - server: myregistry.example.com
        username: myuser
        password: mypassword
      - server: other.registry.io
        username: otheruser
        password: otherpassword

The server field must match the registry hostname exactly as it appears in the image URI (e.g. myregistry.example.com for myregistry.example.com/repo:tag). Docker Hub images (e.g. ubuntu:22.04) have an empty hostname and are not matched by any explicit credential entry — use the Docker config mount approach for Docker Hub authentication.

Precedence

Explicit credentials take precedence for registries they cover. For everything else, Floci falls back to the Docker config file (if docker-config-path is set) and then to an anonymous pull.

Container Log Settings

Configure log rotation for all containers spawned by Floci:

floci:
  docker:
    log-max-size: "10m"   # Max size per log file before rotation (Docker json-file format)
    log-max-file: "3"     # Number of rotated log files to retain per container

Container Labels

Every container and volume Floci creates carries three reserved labels for discovery and cleanup:

Label	Value	Purpose
`floci`	`true`	Umbrella across all Floci emulators — `docker ps --filter label=floci=true`
`floci_emulator`	`floci-aws`	Per-emulator discriminator
`floci_namespace`	(the configured namespace)	Only present when `resource-namespace` is set

Add your own labels with extra-labels — they are applied to every container and volume Floci creates (Lambda functions and code volumes, RDS databases, ElastiCache, OpenSearch, MSK, ECS, ...):

floci:
  docker:
    extra-labels:
      - key: "com.example.project"
        value: my-project
      - key: environment
        value: dev

Or via environment variables (indexed entries, like registry-credentials):

services:
  floci:
    environment:
      FLOCI_DOCKER_EXTRA_LABELS_0__KEY: "com.example.project"
      FLOCI_DOCKER_EXTRA_LABELS_0__VALUE: my-project
      FLOCI_DOCKER_EXTRA_LABELS_1__KEY: environment
      FLOCI_DOCKER_EXTRA_LABELS_1__VALUE: dev

Extra labels are a list of key/value entries rather than a map so that label keys containing dots, colons, or uppercase characters survive the environment-variable naming convention.

Note

Entries using one of the reserved keys (floci, floci_emulator, floci_namespace) are ignored with a warning — user configuration can never break Floci's own container discovery and volume pruning.

Resource Identity Labels

A container backing an emulated AWS resource also carries labels tying it back to that resource, additive to the labels above:

Label	Value	Purpose
`io.floci`	`aws`	Cloud provider, for multi-cloud discovery when several Floci-like emulators share a host
`io.floci.service`	e.g. `rds`	The AWS service the container backs
`io.floci.resource-id`	e.g. `orders-db-primary`	The resource's identifier (DB instance identifier, cluster name, function name, ...)
`io.floci.account`	the resolved account id	The AWS account the resource belongs to
`io.floci.region`	the resolved region	The AWS region the resource belongs to

This makes docker ps --filter label=io.floci.resource-id=orders-db-primary resolve a specific emulated resource to its backing container directly, without inferring it from names or creation order. Applied to RDS, DocDB, ElastiCache (Redis/Valkey and Memcached), MemoryDB, Neptune, MSK, OpenSearch, ECS, EKS, AmazonMQ, MWAA, Kinesis Data Analytics (Flink), Batch, CodeBuild, Lambda, and EC2. ECR's backing registry container carries every label except io.floci.resource-id, since it is a shared singleton with no single resource identifier.

Docker Network

Containers spawned by Floci (Lambda, RDS, ElastiCache, OpenSearch, MSK, ECS) need to be on the same Docker network to communicate with each other and with Floci itself.

When Floci itself runs inside Docker and no network is configured, it automatically detects the current container's Docker network and uses it for spawned containers. You only need to set this manually when you want to force a specific network.

Set the shared network at the top level:

floci:
  services:
    docker-network: my-project_default

Environment variable: FLOCI_SERVICES_DOCKER_NETWORK

Individual services can override the network with their own docker-network setting (e.g. floci.services.lambda.docker-network).

Tip

In Docker Compose, the default network name is <project-name>_default. If your compose file is in a directory named myapp, the network is myapp_default.

Running on Podman (rootless)

Floci runs under rootless Podman, but Podman's network topology needs a few explicit settings that Docker handles automatically. The following configuration is known to work:

podman network create floci-net

podman run -d --name floci \
  --network floci-net \
  -p 4566:4566 \
  -v /run/user/$(id -u)/podman/podman.sock:/var/run/docker.sock:z \
  -e FLOCI_SERVICES_LAMBDA_DOCKER_NETWORK=floci-net \
  -e FLOCI_HOSTNAME=floci \
  floci/floci

What each setting does and why it is needed:

Named network (floci-net) — the rootless default bridge does not assign reachable IPs between containers, so spawned Lambda containers cannot reach Floci. Create a named network and put both Floci and its Lambda containers on it.
FLOCI_SERVICES_LAMBDA_DOCKER_NETWORK=floci-net — makes Floci attach the Lambda containers it spawns to that same named network.
FLOCI_HOSTNAME=floci — gives Floci a stable name that Lambda containers resolve when calling back to the Runtime API.
:z on the socket mount — relabels the Podman socket for SELinux. Without it, Floci fails to talk to the Podman socket: Lambda/ECR container creation errors with java.io.IOException: Broken pipe, and the Floci UI sidecar fails to launch with java.net.BindException: Permission denied. Use the lowercase :z (shared relabel) rather than :Z — the Podman API socket is shared with the Podman service, and :Z applies a container-private SELinux label that can break access. If :z is still not enough on your host, fall back to --security-opt label=disable.

When the Runtime API address is still unreachable

On some Podman network topologies the auto-detected Runtime API address (the host/IP Lambda containers use to call back into Floci) is still wrong, and invocations fail with connect ECONNREFUSED <ip>:12000. Set the address explicitly to bypass auto-detection:

FLOCI_SERVICES_LAMBDA_DOCKER_HOST_OVERRIDE=floci

This forces every spawned Lambda container to reach the Runtime API at the given host (here the FLOCI_HOSTNAME value), skipping Floci's auto-detection entirely. See the Lambda docs for details.

Full Reference

Environment variable	Default	Description
`FLOCI_DOCKER_DOCKER_HOST`	`unix:///var/run/docker.sock`	Docker daemon socket
`FLOCI_DOCKER_DOCKER_CONFIG_PATH`	(unset)	Path to directory containing Docker's `config.json`
`FLOCI_DOCKER_REGISTRY_CREDENTIALS_0__SERVER`	(unset)	Registry hostname for credential entry 0
`FLOCI_DOCKER_REGISTRY_CREDENTIALS_0__USERNAME`	(unset)	Username for credential entry 0
`FLOCI_DOCKER_REGISTRY_CREDENTIALS_0__PASSWORD`	(unset)	Password for credential entry 0
`FLOCI_DOCKER_LOG_MAX_SIZE`	`10m`	Max container log file size before rotation
`FLOCI_DOCKER_LOG_MAX_FILE`	`3`	Number of rotated log files to retain
`FLOCI_DOCKER_EXTRA_LABELS_0__KEY`	(unset)	Label key for extra-label entry 0, applied to every Floci-created container and volume (increment the index for more)
`FLOCI_DOCKER_EXTRA_LABELS_0__VALUE`	(unset)	Label value for extra-label entry 0
`FLOCI_SERVICES_DOCKER_NETWORK`	(unset)	Shared Docker network for all container-based services
`FLOCI_SERVICES_LAMBDA_CONTAINER_NAME_PREFIX`	`floci`	Base name prefix for spawned Lambda containers and code volumes (e.g. `acme` → `acme-<function>-<id>` containers, `acme-code-<function>-<hash>` volumes). Must be a valid Docker name segment (`[A-Za-z0-9][A-Za-z0-9_.-]*`); invalid values are ignored with a warning. See the Lambda docs