3 ms·

Can you point me to an example of what you'd consider a good configuration file? Something that doesn't have comments, and wouldn't be improved by adding any?

mlthoughts2018 8y ago
This project is useful as a toy reference for the 12 factor principles, including making the app totally isolated from any config file (all config must be consumed from the environment). In such a case, you would document artifacts that assemble different environments, with usage instructions outside of any config / container definition / shell script / etc. https://github.com/WASdev/sample.microservices.12factorapp https://github.com/WASdev/sample.microservices.12factorapp
- evil-olive 8y ago
  > making the app totally isolated from any config file (all config must be consumed from the environment) Wait, so is it "config files shouldn't have comments" or "config files shouldn't exist at all"? If all configuration is consumed from the environment, where are the values of the environment variables defined? eg, if instead of {"enable_foo": true} in a JSON config file you have an ENABLE_FOO environment variable, where does the value ENABLE_FOO=1 live? A shell script, a config database such as Consul or etcd, or something else? It can't be turtles all the way down - at some point you have to have the configuration stored somewhere, whether that's a file or a different abstraction like a database. Wherever that storage location is, why are human-readable comments alongside the machine-readable values a bad thing?
  - mlthoughts2018 8y ago
    Nobody’s saying there would be no files anywhere, just not in the application itself. Config files would would be like third party packages that get installed by an evironment orchestration tool (container, chef, puppet, whatever) for purposes of defining an environment. This way the “API” for a third party providing custom overrides at runtime to config is through ENV vars, not editing files. (Creating a modified config file would be for purposes of creating a whole new installable package that third parties can use. Whoever config files are shipped to, sys admins, end users, yourself on your local laptop, those users would never modify the config file — it would be immutable from their point of view and only extended by ENV). So yes, some files store config somewhere to define environments, but what I’m saying is that when these files are treated as separate installable artifacts outside the app itself, then placing documentation into those config files is unwanted, even an anti-pattern because you’d want them to be in a user guide for people to know how to choose between config files and the use case at a high level, that’s the right place to document why foo is set to 57 or something. Putting human readable comments into the actual environment defining config file is bad because these files can become scattered and out of sync, and it encourages reading the file itself as a source of information instead of central usage guidelines. If you also don’t let people inject custom config into the file (use ENV instead) then there’s no reason for the extra hassle, risk of getting out of sync, or risk of mixed signals that it’s ok to edit the file locally.

mlthoughts2018 8y ago

This project is useful as a toy reference for the 12 factor principles, including making the app totally isolated from any config file (all config must be consumed from the environment). In such a case, you would document artifacts that assemble different environments, with usage instructions outside of any config / container definition / shell script / etc. https://github.com/WASdev/sample.microservices.12factorapp https://github.com/WASdev/sample.microservices.12factorapp

evil-olive 8y ago
> making the app totally isolated from any config file (all config must be consumed from the environment) Wait, so is it "config files shouldn't have comments" or "config files shouldn't exist at all"? If all configuration is consumed from the environment, where are the values of the environment variables defined? eg, if instead of {"enable_foo": true} in a JSON config file you have an ENABLE_FOO environment variable, where does the value ENABLE_FOO=1 live? A shell script, a config database such as Consul or etcd, or something else? It can't be turtles all the way down - at some point you have to have the configuration stored somewhere, whether that's a file or a different abstraction like a database. Wherever that storage location is, why are human-readable comments alongside the machine-readable values a bad thing?
- mlthoughts2018 8y ago
  Nobody’s saying there would be no files anywhere, just not in the application itself. Config files would would be like third party packages that get installed by an evironment orchestration tool (container, chef, puppet, whatever) for purposes of defining an environment. This way the “API” for a third party providing custom overrides at runtime to config is through ENV vars, not editing files. (Creating a modified config file would be for purposes of creating a whole new installable package that third parties can use. Whoever config files are shipped to, sys admins, end users, yourself on your local laptop, those users would never modify the config file — it would be immutable from their point of view and only extended by ENV). So yes, some files store config somewhere to define environments, but what I’m saying is that when these files are treated as separate installable artifacts outside the app itself, then placing documentation into those config files is unwanted, even an anti-pattern because you’d want them to be in a user guide for people to know how to choose between config files and the use case at a high level, that’s the right place to document why foo is set to 57 or something. Putting human readable comments into the actual environment defining config file is bad because these files can become scattered and out of sync, and it encourages reading the file itself as a source of information instead of central usage guidelines. If you also don’t let people inject custom config into the file (use ENV instead) then there’s no reason for the extra hassle, risk of getting out of sync, or risk of mixed signals that it’s ok to edit the file locally.