Allow environments/storage backends to be optional (skip if unavailable)

[ChristianMurphy]

Problem

We bake a single flipt-config.yaml into a Docker image that runs in both production (ECS) and local development (Docker Compose). Our config defines two environments:

• Production: backed by a remote Git repo (works everywhere)
• Local: backed by an in-memory store that seeds from a local filesystem path (file:///repo) for quick local iteration

The /repo path only exists in the local dev docker-compose setup. In production, Flipt crashes at startup with:

Error: initializing environment store: environment "local": performing initial fetch: repository not found

The failure happens during environment store initialization, before any fetch policy logic applies. This means a single config can't gracefully degrade based on what's available at runtime.

What we've tried

1. fetch_policy: "lenient" on the local storage backend. Doesn't help. The error occurs during initial store setup (local path resolution), not during a remote fetch. lenient only covers remote connectivity failures.

2. FLIPT_ environment variable overrides: great for scalar values, but there's no clean way to add or remove an entire storage block or environments entry via env vars.

3. Entrypoint scripts with yq to assemble config at startup: this works, but adds operational complexity (extra tooling in the image, conditional logic in the entrypoint, harder to reason about what config Flipt actually sees).

Proposed solutions

Here are a few options we'd love the maintainers' perspective on:

Option A: optional: true on an environment

The simplest conceptual change. If the storage backend for an environment fails to initialize, log a warning and skip it instead of crashing.

environments:
  local:
    name: "Local"
    storage: "local-storage"
    optional: true   # <-- skip this environment if its storage can't init

Option B: Extend fetch_policy: "lenient" to cover local path failures

Today lenient only handles remote fetch errors. Broadening it to also tolerate a missing local repo path (treating it as "empty state" rather than a fatal error) would make the existing mechanism cover this use case naturally.

Option C: Support multiple config files with merge semantics

Allow --config to accept multiple paths or a glob, with later files merged on top of earlier ones. The local-only config would only be mounted in dev:

flipt server --config /etc/flipt/base.yml --config /etc/flipt/local.yml

This is a pattern used by tools like Docker Compose, Helm, and many others.

Context

This seems like a natural extension of the fetch_policy work in v2.3.0 (#4920, #4965). The underlying need is the same: "don't crash when a configured backend isn't available at runtime." The current implementation covers remote connectivity failures but not missing local paths, which creates a gap for teams using a single image across environments.

Happy to discuss further or contribute if any of these directions make sense!

[erka]

Hey @ChristianMurphy. Is there anything that blocks you from doing something like this in your Dockerfile?

FROM docker.flipt.io/flipt/flipt:v2

USER root
RUN apk add git && mkdir -p /repo && git init /repo && chown -R flipt:flipt /repo && apk del git
USER flipt

[ChristianMurphy]

There isn't.
My workaround, that I found a bit after opening this (that feels a bit hack-ish) is very similar, just adding a stage to keep the final image clean.

# Build an empty git repo so the "Local" environment can initialize
# even when no volume is mounted (production). In local dev, docker-compose
# overlays /repo with a volume mount of the real repo.
FROM alpine:3 AS repo-seed
RUN apk add --no-cache git \
    && git init /repo \
    && git -C /repo config user.name "Flipt Container" \
    && git -C /repo config user.email "flipt@localhost" \
    && git -C /repo commit --allow-empty -m "empty init"

FROM docker.flipt.io/flipt/flipt:v2

EXPOSE 8080

COPY --chown=flipt:flipt flipt-config.yaml /etc/flipt/config/default.yml
COPY --chown=flipt:flipt policy.rego /etc/flipt/policy.rego
COPY --from=repo-seed --chown=flipt:flipt /repo /repo

HEALTHCHECK --interval=5s --timeout=5s --retries=5 CMD nc -z localhost 8080 || exit 1

[erka]

I think you're on the right path - a multi-stage build is a great solution.

[ChristianMurphy]

Okay, thanks for the quick answer and feedback! Will stick with the docker approach for now.