Caddy v1 was simple. It was a web server and reverse proxy with an easy to use syntax and great features.
Caddy v2 tries to do so much more that it ends up confusing. The docs now have to be agnostic of configuration language, and in addition to the Caddyfile, there are also myriad commands. It seems the Caddyfile syntax itself has also changed.
Am I overreacting?
Yes you are overreacting.
You can still use v1.
v1 isn’t maintained anymore right?
We can understand even the stuff we bought in IKEA a decade ago can’t reused on our new furniture, our new furniture doing so much than we would have like!
If you have anything specific you need clarified, please ask! We’re here to help.
Vague complaints like this aren’t very actionable, we can’t do anything to improve the situation if you don’t give us any specifics of what you’re finding problematic.
We went through 10-14 months of development and beta versions where feedback like this could have arisen, before it was locked in stone. That was the time to make big changes. Nonetheless, what I’m reading so far isn’t compelling enough that I would have aborted what ended up being our final design and architecture. It’s different, and that’s probably what you dislike.
I can understand that v2 is more complicated. It is, but it’s still fairly easy to use. Anyway, I’ve heard this a lot – let me try to address your complaints here. We’ll have to look at every single claim and get specific in order to improve.
It had serious design limitations though, and we couldn’t fulfill about 200+ feature requests that we can with v2.
This is true if you go into v2 thinking it’s the same as v1. Our v2 upgrade guide recommends “It might be best to go into Caddy 2 with no assumptions carried over from Caddy 1,” because Caddy 2 was rewritten from the ground-up, and assuming it works the same as v1 will trip you up.
It also stresses using our Getting Started tutorial, which we recommend for everyone – it is designed to give a high-level overview of how Caddy 2 works.
I’m not sure what you mean by this. Caddy’s configuration is JSON, simple as that. Its structure is documented here: JSON Config Structure - Caddy Documentation - these docs are auto-generated using a program I wrote, and it’s a very novel concept because of its extensibility, so we’re still getting used to documenting with it. But the structure is there and we’ve tried hard to cover everything.
The Caddyfile adapter has many pages documenting its use here: The Caddyfile — Caddy Documentation - we even have a tutorial to help people learn how to use the Caddyfile here: https://caddyserver.com/docs/caddyfile-tutorial
Other config adapters are third-party modules which our docs won’t cover.
Isn’t it wonderful? We actually have a proper CLI. What is confusing about it? I think the command line is very well-documented on this page: Command Line — Caddy Documentation - we even summarize what every command does, and you can use caddy help or caddy -h to get help, like most proper CLI tools.
A little bit, yes. But not much. For example:
proxy /api/ localhost:9005reverse_proxy /api/* localhost:9005fastcgi / localhost:9005 phpphp_fastcgi localhost:9005It will feel very familiar, but it’s much improved. You can do a lot more with it that you had to resort to hacks for in v1, if it was even possible at all. Most things are “easier” in the v2 Caddyfile.
Maybe.
Our biggest (non-technical) mistake in v1 was touting it as easy to use. Web servers are not easy. They never have been, and they never will be, thanks to the Web and its infrastructure. getting ever more complicated. You’ll have to learn how it works, and although Caddy 2 configs are in many ways simpler and more powerful than in v1, Caddy 2 is not a toy and has a bit of a learning curve. But spend an afternoon learning how it works, and profit for years to come. Apache and nginx were/are no different in this regard: you just have to learn how it works. This is frankly true of any professional tooling.
We’ll do our best to write good docs – we do work very hard on them – but, we have to expect people to read them (we know users don’t a lot of the time, as we post links to documentation that directly answer their questions on our forums here, but the click counter never gets incremented, so we know they aren’t clicking the links at all).
Even if it takes a little good-ol’ synthesis and troubleshooting to figure out the answer to a question, that’s a good skill to have, regardless of how good a software’s documentation is.
You can also make good use of the site search, which can help to teleport you to the keyword you’re looking for.
We have a wiki category on our forum where users can post examples: Wiki - Caddy Community - it’s even linked in our header. This is superior to the old v1 examples repo on GitHub because there are too many possible examples, and the wiki isn’t gated/bottlenecked by our approval process (having to review + merge a PR). Anyone can create wiki entries here.
Anyway, I would recommend just discarding what you know about Caddy and learn Caddy 2 from scratch again, and you’ll quite like it. You will come to realize why a lot of things are the way they are, and appreciate it more that way.
but in fact caddy 1 WAS easy and very much so, I mean it has never been easier for me to at least just prop up a caddy along with PHP for a quick little debug test webserver compared to what I used before. no super complicated and spread out apache/xampp configs, crazy annoying update procedures, NOTHING.
when you just want a simple webserver caddy was excactly that (ignoring that time period where I had to compile caddy myself, lol)
and it made a lot of development stuff easier. a new PHP version is out, okay just let me close on CGI and start the other boom you’re in, oh a new version of caddy came out? close caddy, replace binary, start again, at the very least on windows the webserver did not feel like a burden, and granted once caddy 2 is properly set up, it’s the same but setup just feels at least a little bit least comfortable than before.
also regarding the docs, they are due to caddy2 being still young obviously not overly refined and especially on the caddyfile side, not always complete, like for example it is said that markdown can be done using the templates command/directive/whatever but HOW?
this does not really say how to do markdown with this at all, while in caddy1 there was a wonderfully documented mardown option that couldnt be simpler, add your path, and maybe add some extras for flavor but dead simple if you want
All of this is the same in Caddy 2.
The very first line links to the templates documentation: Modules - Caddy Documentation
Then you can do a Find In Page, or skip that link entirely and just do a site search for “markdown”:
The first result takes you to this doc:
markdownRenders the given Markdown text as HTML.
{{markdown "My _markdown_ text"}}
I don’t get what could be simpler. It’s all right there. You just have to read it.
Hi,
I didn’t know about v1 and I know what it is to start from the ground when you already have a working tool (there a bit of feelings to deal with…).
That said, I spend a lot of time to understand the v2 logic (it is high level and it does not mean easy level). It can be frustrating but not for long as the doc helps a lot (I don’t have production site with specifics need, it’s a lot easier I know).
The docs still need some more examples (but not too much), I could have save some time with it (even if the practice I had is not useless anyway).
I can help for that! What kind of examples do you want? (I can even translate in french if needed).
As a memo for myself, I’m using this server:caddy [« Wikidd »] (in french for now)
Another attempt in english : caddy [« Wikidd »]
If it’s helpful, I would be glad to write up some generic examples (maybe not only the Caddyfile).
Good luck!
V1 documentation was easier to understand. This tutorial (https://caddyserver.com/v1/tutorial/caddyfile) had all the information I needed to run my site.
V2 documentation introduces complexity too early (JSON config, API) and reads more like a manual instead of a tutorial. There should be sample Caddyfiles for common use cases, like the ones here (GitHub - caddyserver/examples: OBSOLETE. This repo was for Caddy v1. For v2 and newer, see our forum's wiki category.).
My use case is running a PHP web server with CORS enabled. The v1 cors plugin syntax is easier to read:
cors / {website}
than v2, which is:
headers / {
Access-Control-Allow-Origin {website}
-Server
}
This also applies to the ipfilter plugin. I prefer shorter syntax to address these features.
I am running a few sites on v1, and would like to have access to the documentation in the future. The v1 website says it will go away soon. Why? Unless there are security implications, v1 shouldn’t be marked as obsolete. I would like to continue working with v1.
FYI you need to remove the / for that to apply to all paths. v2 path matching is exact match. This is all explained in the Upgrade Guide:
We’re working on it. v2 just came out, examples don’t just appear out of the blue, it takes time and users to come up with decently representative examples from working configurations.
We’re pointing people to the wiki on this very forum as the ideal place for examples and guides:
Are you talking about these pages?
Because those are definitely tutorials. They even appear under the “Tutorials” section in the sidebar.
The more “manual” style pages are these:
well if that’s something you have to insert into the pages it would that mean you cannot just serve markdown files as they are?
You can serve an HTML file which acts as the layout which includes markdown files.
You can look through the source of the Caddy website to see how it’s done:
Specifically, take a look at the Caddyfile, and src/docs/index.html.
Welcome Renato –
What is missing from the new tutorial? https://caddyserver.com/docs/caddyfile-tutorial - it was based on the old one and contains nearly analogous information, even in a parallel presentation (obviously with a few changes/improvements).
Is this referring to the Getting Started tutorial now? Getting Started — Caddy Documentation – these are crucial for understanding your new web serer. One thing I am pretty convinced about is that users need to understand these aspects of Caddy because it is so unique from other servers.
Caddy 2 is not a toy; it is something that needs to be understood in order to be used well.
That’s what our forum’s new wiki category is for. 
Wiki - Caddy Community
There’s nothing stopping anyone from writing these directives for v2 as well! (Though it is not strictly necessary to achieve the functionality due to Caddy 2’s advanced matching and header manipulation capabilities – but more directives can always be written for convenience, if desired.)
Did you know it took years before Caddy 1 had these features? I’d say we’re doing pretty well for where Caddy 2 is at, just a few weeks after its first tag.
The message in the banner is urgent to convince people to upgrade, even though we will probably have a link to a PDF of the docs or something, somewhere, at some point. I will suggest that you upgrade nonetheless, since Caddy 1 has bugs and stuff that can’t/won’t be fixed.
You can serve any static files as they are. If you mean markdown rendered as HTML, then, what use would that be? They would have no style, no page title, no behavior (optional, but still, most sites use a few lines of JS at least), no navigation, no header, no footer, etc. Markdown files are kind of useless without a template, hence the templates directive.
style and js was in caddy1 set centrally which makes sense when you do not want to modify many markdown files just to fit the template.
in fact you could even throw in a global template to use for all markdown files at a specific place allowing even more flexibility while keeping the ability to just use markdown files.
You can do the same in Caddy 2, that’s exactly how we do our docs. One file with the styles and template, then countless other Markdown files that get rendered into it.
okay that is totally not obvious that the tpl works that way. I just thought you would have to make each page as a template with places for variables like
{{env "VAR_NAME"}}
markdown text with something like this
{{markdown "My _markdown_ text"}}
and server side includes
{{include "path/to/file.html"}} // no arguments
Thanks Matt and Francis for the links and feedback! This Caddyfile (Example: WordPress) is a good starting point for my upgrade to v2. I’ve read the documentation and understand the directives better now, but in the spirit of minimal configuration, I think the v2 documentation can perhaps offer sample Caddyfiles for PHP or .NET web servers right in the beginning so users can get started quickly without having to read too much into other details.
There’s a WordPress example right here:
None of us have experience with .NET, but it would probably just be a simple reverse_proxy. A .NET example would be basically meaningless.
I don’t really think we need examples specific to those things in the docs. That’s exactly what the wiki category is for. Some simple PHP examples make sense to have in the docs though, because we have a directive dedicated to it.
