oscm-deployer: Ideas for improving usability and convenience

[shimizuf]

Background The Docker based deployment is already much more convenient and reliable than the traditional installation method. However the var.env file contains a large number of settings which can cause confusion to a new user. Examples:

• Some settings are mandatory and some are optional
• Some settings are not self explanatory ("what does it do?" / "what should I set?" / "do I need it?")
• Configuring variables in an invalid format or setting them empty causes an error during DB initialization. This may not be obvious to new users.

Tasks

• [x] Collect ideas to improve the usability and decrease the likelihood of configuration error when using the deployer
• [ ] Decide if any of these can be implemented to further improve manual deployment
• [ ] Implement if applicable

Some ideas

1. Provide an additional var.env template in the deployer. This template may be pre-filled with data which is mostly already in the comments. This decreases effort and error probability for the user, and shows the correct format. The new template could be provided by the deployer only when an env variable is set; the current template can remain the default. This way would not cause additional effort for changing existing build processes. Example: docker run --name deployer1 -e EXAMPLECONFIG=true [...]
2. To differentiate between mandatory and optional settings, the optional settings might be commented out by default in the var.env template. This way there is a better chance that no mandatory variable is forgotten. At the same time this decreases the chance that an optional variable is set empty but not commented out, which causes an error later.
3. It may be worth switching from using envsubst in the scripts to substitute the variables to a different solution - possibly self-written - which handles certain configuration errors better. But this will likely create larger efforts.

[GoebelL]

Great ideas. Option 2 is minimal effort. Let's start with this.

[GoebelL]

Clear documentation is essential for a user friendly configuration handling. I suggest each setting or at least each group of settings needs a minimum description or instruction how to use. Optional and advanced settings shall be equipped with comments pointing to the user documentation.

A small risk of option 2 is how to make aware about such convention to everybody who is changing templates or related implementation. As there is no easy way to automatically check or enforce such rule, new optional settings may slip in that aren't disabled. I suggest to add mandatory reviewers from documentation team.

[GoebelL]

Adding @gertipoppel

[gertipoppel]

More extended documentation already exists (Operator's Guide) together with suggested samples. Should we simply include the doc in the var.env template file?

[GoebelL]

@gertipoppel

Should we simply include the doc in the var.env template file?

in order to avoid much duplication, I suggest to add documentation links in the var.env template where applicable. E.g.

# For details refer to Appendix A.1 in the Operator's Guide,  https://github.com/servicecatalog/documentation

[GoebelL]

Implemented idea 2 - https://github.com/servicecatalog/oscm-dockerbuild/pull/140/commits/98cfe8a563413f41bdac5fd9d09262920877881d

[GoebelL]

Done in 19.0.