[goliatone]

I think there is a more positive interpretation of comments like GP regarding the v2 documentation. There might be content but is not discovered easily. I have experienced this myself, the structure of the docs, currently, is not structured in a way that makes it easy to find what you need.

A lot of the meat is interspersed in random replies to questions both in github issues and community posts. Also, I have the impression that some content is not accessible (linked?) from the side bar in the docs page but only through links from content pages. Most google and github search return content for v1, most tutorials online are for v1.

I don’t think the feedback was meant to detract from the effort put to document things, it just highlights that current documentation could be better organized.

[lmeyerov]

A belated congrats!

We love Caddy, especially for the read-friendly nature of Caddyfiles and the built-in LE. But, we do find the docs and plugin situations difficult enough for deeper customization + debugging that we still also use Nginx elsewhere, and are only now getting serious about a V1 -> V2 migration. The below are about our V1 docs experience and looking at V1 -> V2 migration two times and being scared off, and hopefully actually doing it the third time.

1. Docs:

-- Common full working configurations are unclear: Finding them requires Google searches hitting broken examples in support forums, when you are lucky that they exist. This is common stuff like proxying, auth API gates, etc. (There was a small V1 github repo that was helpful, it may exist for V2 as well now?)

-- The doc style seems to prioritize terseness vs. clarity. (Even in math, we know an error-correcting language uses repetition & spacing to provide value beyond what a minimal number of characters can do ;-))

-- Examples... aren't. Ex: They are generally 'out-of-context', so unclear how to put into a full working configuration, even at the syntax level

2. Plugins:

The philosophy of pushing basic capabilities to the community via plugins makes sense for a small-staffed effort, though like the JavaScript nodejs/npm situation, that causes its own problems. The above examples like auth are so basic that even if they're via the community, they're part of a migration of a real implementation, and even if the core is fine, they're central enough that they need to be great too: features, docs, etc. Node kind of got away with it b/c a few people took on big lifts for stuff like the HTTP libraries, and that was a big part of the success. Our earlier analysis of basic V2 plugins showed they were a WIP, and while we're now revisiting, it was disappointing to see V1 stopped.

Hope that helps! We are not paying users, but we do evangelize to federal + F500 IT types.

[mholt]

Great feedback, thanks.

Regarding full configurations, what do you want to have there? It seems infeasible to provide a full configuration that works for everyone, since everyone's sites and deployments and requirements are different, even if a little bit. Aren't there thousands, nay millions, of ways to configure any number of sites and services in any number of environments? I hesitate to get in the territory of "this is exactly how you do this, no need to read and learn how it works" -- because then we have a lot of uninformed, confused users (we learned this from experience in v1). I think our biggest mistake in v1 was making things too easy.

As for plugins, Caddy 2 is nearly infinitely extensible, and I myself can't commit to building everything that is needed... we definitely rely on the community to build what they need, and then share it. It worked in v1, I think it will work in v2, too! It will also happen much more quickly and probably be higher quality in the long run.

[lmeyerov]

Maybe as an exercise, try working backwards for some top 5 scenarios (reverse proxy, multi-domain, static server, bastion, ...), or better, record a session of someone trying it out for the ~first time. Ex: "I'd like to host multiple sites on one subdomain: that means reverse proxying several pages and doing an auth header check (ex: JWT)".

As a user, I'd check the tutorials + corresponding docs. It's tantalizingly close, but some quick gotchas already:

-- There is a reverse proxy tutorial... but it's too minimal. No multiple paths, route rewriting, ... . It does get you to the reverse proxy directive docs, which has more examples, and then another jump to matchers.

-- There is no auth tutorial section, which I would have thought would be somewhere in the ~top 5 scenarios. A search for 'jwt' gets me to the JWT plugin, but unclear what a sample config for a route would be, say for a boring Django / Rails / auth0 setup of "Authorization: Bearer ..." -> "/some/check/route": https://caddyserver.com/docs/modules/http.authentication.pro....

One of the toughest parts of writing is reading your own work :)

[tpetry]

Good ideas, and maybe add some easy starters: This is how you use php‘s framework laravel, this is how you do reverse proxying to nodejs.

The crucial part for me would be that every of these examples will be done with the old Caddyfile and the new json format. With enough samples you would get a good feeling on how to transform these caddyfiles to the json format.

[francislavoie]

To be clear, you can still use the Caddyfile in v2, and frankly it's what I would recommend, especially for a Laravel app. It'll just be as simple as this:

    example.com {
        root * /var/www/public
        encode gzip
        php_fastcgi unix//var/run/php-fpm.sock
        file_server
    }

If you need any more help, please come by the community forums, and I can be sure to get you sorted: https://caddy.community

[mholt]

> I have the impression that some content is not accessible (linked?) from the side bar in the docs page but only through links from content pages.

That may be true, but we have hundreds of content pages in the new docs. It's a bit unmanageable to have them all in a sidebar.

Not sure what we can do about search results and content on other sites, either, other than encouraging contributions to our wiki so people can find things easier.