4 ms·

I'm hitting the same problem a lot with a bunch of things. Concourse CI is the one I'm running up against this today - I'm taking over a partially built instal

I'm hitting the same problem a lot with a bunch of things. Concourse CI is the one I'm running up against this today - I'm taking over a partially built installation which has all sorts of hard-coded config environment variables that I'm trying to figure out their purpose. Their documentation has basic getting-started stuff[1], but doesn't list all the config variables and their use. It's open source, so I cloned the repo, but they don't directly reference the environment variables there, either. Compare that to, say, Ansible's documentation - it exhaustively lists all the options[2] and what they're used for, with links to other related documentation. [1] https://concourse-ci.org/concourse-web.html https://concourse-ci.org/concourse-web.html [2] https://docs.ansible.com/ansible/latest/reference_appendices/config.html#environment-variables https://docs.ansible.com/ansible/latest/reference_appendices...

vito 7y ago
(Concourse co-creator/OSS lead here.) Our CLI hasn't really aged well and that's something I'd like to address soon - probably going more in the direction of config files instead of flags/env vars. It'd be a lot easier to document with a proper schema. Thanks for the feedback and sorry the experience is still pretty rocky!
- paranoidrobot 7y ago
  Awesome, thanks. Honestly the whole application seems pretty good - but everything is focussed on more hello-world stuff, which is great for getting going on my machine - not so great for running it for real. Whether you use environment vars or a config file, I don't mind - one benefit environment vars gives is that setting CONCOURSE_BIND_IP to the instance's IP is relatively simple, eg on AWS: CONCOURSE_BIND_IP=$(curl http://169.254.169.254/latest/meta-data/local-ipv4 http://169.254.169.254/latest/meta-data/local-ipv4) If it's a config file then I need to update that before the application starts, which is more fiddling.
  - vito 7y ago
    Yeah that's a good point. There are definite trade-offs to going for only one or the other. If there's a nice way to support both without too much maintenance overhead, that'd be my preference. There are a few popular Go libraries which support that, like https://github.com/spf13/viper https://github.com/spf13/viper - which we'll probably consider switching to as part of a general CLI overhaul. For a long time now we've been primarily focusing on the core design, concepts, and architecture at the expense of documentation and introductory material and outreach - we've never had a dedicated technical writer, so documentation is really best-effort. Now that the dust is settling on our roadmap I feel a lot more confident in increasing our focus on onboarding, operability, and developer/user experience in this coming year. :)

vito 7y ago

(Concourse co-creator/OSS lead here.) Our CLI hasn't really aged well and that's something I'd like to address soon - probably going more in the direction of config files instead of flags/env vars. It'd be a lot easier to document with a proper schema. Thanks for the feedback and sorry the experience is still pretty rocky!

paranoidrobot 7y ago
Awesome, thanks. Honestly the whole application seems pretty good - but everything is focussed on more hello-world stuff, which is great for getting going on my machine - not so great for running it for real. Whether you use environment vars or a config file, I don't mind - one benefit environment vars gives is that setting CONCOURSE_BIND_IP to the instance's IP is relatively simple, eg on AWS: CONCOURSE_BIND_IP=$(curl http://169.254.169.254/latest/meta-data/local-ipv4 http://169.254.169.254/latest/meta-data/local-ipv4) If it's a config file then I need to update that before the application starts, which is more fiddling.
- vito 7y ago
  Yeah that's a good point. There are definite trade-offs to going for only one or the other. If there's a nice way to support both without too much maintenance overhead, that'd be my preference. There are a few popular Go libraries which support that, like https://github.com/spf13/viper https://github.com/spf13/viper - which we'll probably consider switching to as part of a general CLI overhaul. For a long time now we've been primarily focusing on the core design, concepts, and architecture at the expense of documentation and introductory material and outreach - we've never had a dedicated technical writer, so documentation is really best-effort. Now that the dust is settling on our roadmap I feel a lot more confident in increasing our focus on onboarding, operability, and developer/user experience in this coming year. :)