Docker Compose Deployments

[bradleystachurski]

What do we want to do with Docker Compose deployments?

We're getting repeated requests for Docker Compose support (3+ separate asks in the past two weeks). While node-in-a-box solutions handle bitcoin node integration elegantly, there's a persistent group of Docker users who won't use these solutions but aren't equipped to debug production deployments themselves.

We have a new feature that allows fedimintd to start with both bitcoind and esplora connection info, gracefully falling back to esplora if bitcoind is unavailable. This would let us ship a Docker Compose that actually "just works." Users get started immediately with esplora while their bitcoin node syncs in the background. Once synced, it switches to the local node automatically. If the node ever has issues, it falls back to esplora so the service keeps running.

Proposed Approach

Phase 1: Validate the fallback feature We need production validation that the bitcoind -> esplora fallback works reliably before shipping any Docker Compose.

Phase 2: Ship opinionated Docker Compose (once confident in fallback)

• Include both pruned bitcoind (500MB) and esplora connection parameters
• Single command: docker compose up -d and nothing else
• Automatic progression: esplora (immediate) -> bitcoind (once synced) -> esplora (if node fails)
• Zero configuration options exposed to users
• Explicit: we ONLY support this exact setup, no modifications, no external nodes

This approach gives users the immediate satisfaction of esplora with eventual sovereignty of their own node, without requiring any technical decisions or manual switching.

Questions

1. What validation do we need for the fallback feature? How many production deployments? What failure scenarios should we test?

2. Are we aligned on the "zero configuration" approach? No environment variables, no options, just docker compose up -d?

3. Support boundaries? I propose we support the exact Docker Compose we provide (best effort help with issues), but modifications are unsupported. Realistically we'll still help users with funds at risk, but we should set clear expectations about what's officially supported.

4. Should we consider not supporting Docker Compose at all? Even with the fallback feature working perfectly, is the support burden worth it versus continuing to point users to node-in-a-box solutions?

Once we're confident in the fallback mechanism, we can ship something extremely simple that actually serves these users well. Until then, we keep pointing them to node-in-a-box solutions.

[bradleystachurski]

Some additional context from @elsirion from an earlier discord message I just recalled 🙈

we should probably also take a look at our docker images again: ideally we'd have a plug'n'play version that uses bitcoind+a mempool space fallback with a reverse proxy for the admin UI that uses a self-signed cert so users can do TOFU and access the UI via IP address

[m1sterc001guy]

I agree with all of the above except including a pruned bitcoind docker image in the docker compose. IMO we should make our docker compose as simple as possible (so that there's less to maintain for us), and including bitcoind opens up a bunch of configuration options that we now need to have an opinion on (a pruned node vs full node is an example).

I think our docker compose should have 1 image: fedimintd, with the environment variables for esplora already configured with a default, and the environment variables for bitcoind included, but commented out (we can include helpful comments for users on how to configure this, similar to other sample files where options are commented out by default).

I believe this has the same affect that you describe above, it "just works" when you run docker compose up -d, but in my proposal it will default to esplora unless the user configures bitcoind.

IMO users that are technical enough to run a docker image should be able to modify a docker-compose.yml file to add config for bitcoind. That same persona also likely already runs their own bitcoin node. I think this is a reasonable technical bar, we're not requiring needing advanced devops experience, just someone who knows docker and runs their own bitcoin node.

[m1sterc001guy]

After chatting with @bradleystachurski, I think it would be best to just ship an esplora docker compose first, then we can add in the bitcoin core connection stuff later. Ideally we should validate the bitcoin connection before DKG, so that the user gets early feedback if they have configured something incorrectly.

[elsirion]

Since https://github.com/fedimint/fedimint/pull/7687 got merged, should we close this issue? We didn't go the fallback route yet, so if we want to keep the issue open I'd propose to rename it to clarify the smaller scope of enabling bitcoind+esplora fallback deployments.