I would remove the instructions to install docker: people can see them in the docker documentation, it doesn’t make sense to include them somewhere else.
Also I would use a .env file to manage the env variables, without requiring the user to modify the docker compose file.
It’s very likely that people will version the yaml file, so it’s not a good idea to keep secrets in plaintext there.
I would not remove them, but place them elsewhere, linked from the point you should run them at the install process.
It's very useful to have a complete 'getting started' page that get you from zero to working, without assuming that the reader understands what every intermediate step means. But as you said, the parts that are dependencies for other products can be encapsulated so that savvy users can skip them easily.
The instructions to install Docker are clearly wrong on many Linux distributions. They add very little value, and are yet another thing that has to be maintained.
The docker installation script is for Ubuntu. I added it to help some users get started pretty quickly.
On the installation page, there is a link to the official Docker guide which comes first. That should help other users with an OS-specific installation guide.
This sounds right until you have to version your docker-compose file.
Storing passwords or secrets in git should be avoided; the .env file structure allows you to leave untouched the yaml file. Anybody changing it? Git pull, and you’re ready to go, since you didn’t change the yaml file and you don’t have to substitute secrets again.
I don't disagree, but I think you're conflating secrets with environment variables. Yes most secrets are (or should be at least) passed in through env vars, but there's also a ton (in some apps 80% to 90%) of configuration that aren't secrets. I also dislike when people treat every config value as a secret. Secrets require additional overhead and care, and burdening yourself (or another dev or operator) with that in order to tweak a completely non-secretive value is unnecessary and IMHO often counterproductive.
For secrets, a .env file is fine for local dev and docker-compose IMHO. The "hidden file" nature of a .env is a good fit for secrets. (For prod I prefer K8s Secrets or Vault or similar)
I've had to debug by tuning multiple vars and compare the results, .env files make this a much cleaner experience especially if the CMS supports a .env file name parameter. I can keep multiple .envs and switch between them easily and know for certain that a change in behaviour isn't due to fat fingering something in the compose file.
In the end it's just personal preference. I get where you're coming from.
Also I would use a .env file to manage the env variables, without requiring the user to modify the docker compose file. It’s very likely that people will version the yaml file, so it’s not a good idea to keep secrets in plaintext there.
https://docs.docker.com/compose/environment-variables/set-en...