We use Caddy for serving our free dashboards and status pages on your own domain at https://checklyhq.com
It was not super easy to set up. I think the whole config is 20 lines or so, but the docs, naming and functionality of how Caddy actually interfaces with LE was tricky to find out. Basically had to scrape together answers from various GitHub issues etc.
What did you find unclear, specifically? We encourage users to come ask for help on our forums, we'll gladly explain everything you need to know. https://caddy.community
Our use case was: "serve SSL certificates on the fly for users hitting :443 AND users hitting *.checklyhq.com, then proxy some content."
The documentation looks visually nice, but is hard to parse as the layout of the config file (and the hierarchy of the items in it) is separate from the explanation of what they do. I was continuously doing a Ctr+F to find words on the page.
Last thing. The docs present a lot of config examples in snippets, but seeing how to use them in a full, syntactically correct file was hard. I felt I was missing the big picture.
Sorry to not be more concrete, it was some time ago.
Regarding clickable bits in the docs, those are set up with some JS I wrote which tries to dynamically add links to certain things. I only set it up for Caddyfile directives and for the global options page in particular. Our docs are in markdown so any linking of things needs to be wired up after the fact on page load with some vanilla JS. I'll look into improving that for some more pages.
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
It's relevant to the discussion. No other server with ACME supports multiple issuers by default. It speaks directly to the point being made in the linked article (and other previous articles written by Scott).
Yes you can configure Traefik with other issuers, but it does not support having multiple configured at the same time and failing over between them in case something goes wrong. That's the point being made in the article. Caddy does this.
[0] https://caddyserver.com/docs/automatic-https#overview
[1] https://zerossl.com/