This probably sounds stupid, but the implied $PWD for the static file server in the Caddyfile tutorial [1] confused me for about 15m because I was trying to run it in Docker.
The common patterns [2] in the reference section shows a better example, but I assumed the reference was a detailed reference, not beginner docs.
So I would say convention / implied config is great once you know how everything works, but it’s awful when you’re trying to learn because you have no idea what’s actually happening. I think the getting started config would be much better if it showed the 5-10 things that most people would expect to see (protocol, port, www-dir, etc.) and then described the shorthand version where all of that’s implied. As is, I have to go look up what the defaults are for all those things and the time it takes is way, way more than I’ll ever save by having that config implied.
Have you ever seen a config file where everything is commented out, but shows every option and the default value? I love those configs.
Docker does make easy things hard. (And yes, I know, sometimes it makes hard things easy.)
> I think the getting started config would be much better if it showed the 5-10 things that most people would expect to see (protocol, port, www-dir, etc.) and then described the shorthand version where all of that’s implied.
That may be true, but we also get a lot of compliments for our current docs, that Getting Started is just what they needed to get going. We also know from experience that a lot of people don't read, and I'm afraid that by showing overly-complex configs, people will copy-and-paste them and just use them blindly without understanding them or trimming them down. Then we have a bunch of bloated configs out there, and oftentimes, we've found that removing things from Caddy configs solves problems.
> Have you ever seen a config file where everything is commented out, but shows every option and the default value? I love those configs.
Funny, I hate those. I want to have a minimal file that I feel like I crafted just for my purposes, rather than taking some boilerplate and trying to coerce it into working for me. I also understand my tools better this way.
One of the core opinions of Caddy is to build things up to suit your needs, rather than tearing things down to make them work.
> Have you ever seen a config file where everything is commented out, but shows every option and the default value? I love those configs.
> Funny, I hate those. I want to have a minimal file that I feel like I crafted just for my purposes
There is no harm in providing the full config and allowing the user to minimize it.
At least that way I can do a `grep -v ^#` or something to avoid showing the comments and still get a minimal file when I want to see the minimal version
The common patterns [2] in the reference section shows a better example, but I assumed the reference was a detailed reference, not beginner docs.
So I would say convention / implied config is great once you know how everything works, but it’s awful when you’re trying to learn because you have no idea what’s actually happening. I think the getting started config would be much better if it showed the 5-10 things that most people would expect to see (protocol, port, www-dir, etc.) and then described the shorthand version where all of that’s implied. As is, I have to go look up what the defaults are for all those things and the time it takes is way, way more than I’ll ever save by having that config implied.
Have you ever seen a config file where everything is commented out, but shows every option and the default value? I love those configs.
1. https://caddyserver.com/docs/caddyfile-tutorial
2. https://caddyserver.com/docs/caddyfile/patterns