Avoiding `.env` in revision control while still being able to open source on a whim

Question

From the 12-factors, III Config:

A litmus test for whether an app has all config correctly factored out of the code is whether the codebase could be made open source at any moment, without compromising any credentials.

but then...

Another approach to config is the use of config files which are not checked into revision control, such as config/database.yml in Rails. This is a huge improvement over using constants which are checked into the code repo, but still has weaknesses: it’s easy to mistakenly check in a config file to the repo; there is a tendency for config files to be scattered about in different places and different formats, making it hard to see and manage all the config in one place.

Our system is a bunch of microservices. Each microservice is an "app", per 12-factor. I like the idea of being in the mindset that we could decide on a whim to open source one of them and we should be able to do so because it keeps us accountable; codecov, being responsible about secrets in code and being as frictionless as one can be when onboarding newcomers..

But an open-source component should be easy to run and demo. How can Jack from the other side of the world, run and demo our open source component he just cloned, if i don't check at least an .env that describes required ports etc?

I find READMEs of the type:

"Wait.. wait.. before you run this, do X on port Y...oh and also this, and also that".

to be in bad taste.

PS: This question is similar but not a dupe. The OP could use something like Vault and get it over with; that's not an option here.

Answer 1

Here's the possible options I can see:

• Include a configuration script (that is checked in) that builds a config file pointing to your demo environment. This could also prompt the user if they want to initialize their own environment instead. Instructions would suggest running this on first install.
• Hard code defaults into the app that point to your demo. If no config file is found, use those defaults.
• If on first run, no config file is found, build one pointing to the demo.
• Include a default config file that is checked in and points to the demo. This could include (commented out?) templates for the user to customize. (maybe call it env.dist? to be copied to .env which is listed in .gitignore)
• Use a tiered config file system that allows higher priority config files to override all or part of lower priority config files. Highest priority config files would be local and outside of your repo. The lowest priority config file would be checked in and point to your demo. Then the demo config would be used if all the rest were not found.

Answer 2

But an open-source component should be easy to run and demo.

The unspoken caveat here is that a component does not necessarily carry the responsibility of providing the entire stack in and of itself. This is the software equivalent of "batteries not included".

Yeah, it would be great customer experience if you could provide some batteries so they can use your device immediately, but this becomes less justifiable as the complexity of your "battery" increases. There might even be cases where it's not meaningfully possible, e.g. if your tool is an improvement that's supposed to go on top of another tool. The aftermarket floormats I bought don't need to come with a demo car, so to speak.

Using a .dist file here is usually a good compromise between the two. It provides an easy default config file, while not actually being in place (due to the added .dist file extension). This requires minimal user interaction, i.e. copying the file and renaming it from .env.dist to .env. At the same time, your gitignore can be configured to ignore .env itself, so an "undisted" file doesn't sneak its way back into the repository.

This dist file could contain usable demo config values, or it could just contain documentation comments on what kind of information the user needs to source in order to get your tool up and running (e.g. an API key for an external service). Whether or not you're able to provide workable default values is very contextual and not universally answerable.