Hi all, just started my way through OpenZiti. I noticed something about the quickstart guide for Docker Compose Locally. Here are the points:
The version parameter is deprecated
If you have a .env file in the same directory as that of the docker-compose.yml file the values will be available automatically. Hence, mention of env_file would be redudant
There have been new specs in the Compose File where one can use volumes_from parameter to make sharing data via volumes perhaps easier
If you want I can work on a PR for the same and improve the QuickStart Docs + Compose file. Not sure what the current contributing policies are for the project
Thanks for looking so closely at the compose file, much appreciated and great feedback. It’s a really fine line between providing too much docker information to people and not enough. It’s always difficult to judge.
As for contributing, we accept contributions, sure. It would probably be helpful to agree on a direction before asking you to set off on something, but we’d definitely appreciate the effort if you wanted to contribute back.
Maybe outline what it is you would propose here or on a github issue? Then me, @qrkourier, @gberl002 and other community members and take a look and see which bits make sense to us? It’s always good to start small though, if there are small incremental changes, those are always more easy to adopt.
Again, thanks for taking a look at the repo! Cheers
In a nutshell, I think I can start with Points 1 and 2 for the docker-compose.yml and subsequently adapt the documentation for the Local - Docker Compose | OpenZiti.
The Points 3 and 4 are more complicated and more of a nice to have.
I think the overall purpose is to improve the UX for Ziti with Docker Compose, especially when it comes to a quickstart. This implies simpler and less commands in the documentation and a quick prototype that can convince someone to go even further.
We could omit version top-level element, but it may still be useful for reverse-compatibility. Now that version is merely informational in latest Compose, my recommendation is to stop pinning a particular minor version of the spec, and only pin the major version, i.e. version '2' or remove the version element as you suggest. Here's the latest spec for our reference.
This raises the question: Does pinning the previous major release v2 help out a significant portion of users who can not parse a v3 spec unless they install additional, newer software? My hunch is this is not a significant value, and it makes more sense to stay with the times and either pin v3 or remove the element entirely.
Correct, it's redundant and harmless. It may still be useful for a new Compose user to have the insight the .env file is used to source environment variables. I don't feel strongly about this one, but I think the intention was to "call out" the importance of the .env file in case the user wasn't aware of how it's handled by Compose.
I agree volumes_from would be more clear if there were only one directional flow of data in the named volume, i.e., being provided by one compose service and consumed by another. This Compose project uses the named volume for multiple flows of data, so expressing a single direction of flow would be more confusing than the current implication that the named volume acts like a shared data backplane for all services.
A possible improvement comes to mind, separate named volumes for each type of data and a single, directional flow of data. In that design it would be more clear to use volumes_from in each consumer. For example, data that is provided by the controller and consumed by the router would live in a meaningfully-named volume that's mounted :rw on the controller and :ro on the router. I'm unsure this is worthwhile or even feasible without first auditing all of the data.
On balance it seems fine to keep using the singular named volume as a general-purpose data backplane.
I see that we're already using depends_on extensively in this Compose project, and I think that means that whatever Compose Service is depended upon is by definition an init container. Is that how you understand it?
Is your idea to translate the scripted health checks into the Compose file YAML as dependency health checks to clarify the initialization success criteria?
My hunch is this is not a significant value, and it makes more sense to stay with the times and either pin v3 or remove the element entirely.
I agree. Since the Documentation specifically mentions Docker Compose v2 it might not be of any significant value at all.
Does pinning the previous major release v2 help out a significant portion of users who can not parse a v3 spec unless they install additional, newer software?
” the importance of the .env file in case the user wasn’t aware of how it’s handled by Compose.
I think the heredoc example for the content of the .env should exist in order to understand the Env Vars and their values. I was suggesting removing the env_file array in the compose file.
As mentioned previously Points 3 and 4 don’t need to be integrated. They may be kept in mind for perhaps a complex example for the future. Regarding the depends_on you can refine the startup dependency even further based on service status. i.e., healthy, started and running. This might be interesting for the init-container example or maybe to do some initial provisioning with credentials etc. However this might require a bit more testing or a rather sophisticated example which does not really make sense for a Quickstart Guide.