Incorrect Docs for php_fastcgi or incorrect behavior of route

(I’m tired and would like to have a simple explanation of an example from the docs. Therefore I’m not posting a full Caddyfile.)
And I’m to 99% sure I found the issue which is a ridiculous one.

1. Caddy version (caddy version):

v2

2. What I did

Delete php_fastcgi from Caddyfile and replace with the long version from the docs.


With the following edit of using
try_files {path} {path}/index.php
instead of
try_files {path} {path}/index.php index.php
(^just to be complete, doesn’t matter here)

3. The problem I’m having:

caddy reload fails

4. Error messages and/or full log output:

reload: adapting config using caddyfile: parsing caddyfile tokens for 'route': /myPath/Caddyfile:34 - Error during parsing: unrecognized directive: @canonicalPath

5. What I already tried:

I placed the named matcher @canonicalPath outside the route directive. And used the reload cmd again.
To no surprise I receive the following error:
reload: adapting config using caddyfile: parsing caddyfile tokens for 'route': /myPath/Caddyfile:45 - Error during parsing: unrecognized directive: @indexFiles

5.2 What I did continued

I placed the other two named-matcher outside the route directive and the reload worked. And with that I’m done after searching for 2-3 hours for a result because of incorrect docs (?).

6. Links to relevant resources:

Conclusion

This clearly tells me, I’m not allowed to use (like in the form from php_fastcgi) named-matcher within the route directive. And the route directive docs themself only allow other directives.

Actually, I should create a github Issue for that one, and maybe with a PR.

This has been fixed on master already, just hasn’t been in a tagged release yet.

That reminds me of still waiting for v2.2 - oof.
Hope such things will be released a bit quicker in the future. Or if updating the docs is quicker, then pls add a note there that xy only works with v2.2.

We’re all busy people. @matt is the primary maintainer and his time is split across a ton of tasks already. Caddy’s a relatively small open source project, and there aren’t many developers working on it. I try and do as much as I can to fill the gaps, but I have my own full time job.

v2.2 was supposed to be released like a month ago, but things happened that delayed it, and we’re spending that extra time to make v2.2 extra juicy with some more new features and fixes.

This specific example for php_fastcgi was written as a “this is what php_fastcgi does in theory” example (because in reality, it’s some Go code that assembles the config to have that sort of effect), not so much meant to be used verbatim.

Named matchers not working in route blocks was an oversight and it wasn’t obvious how to fix until I did some work on implementing handle_path a while back, and the added experience made it clearer how to solve this case.

Edit: That fix is in v2.2.0-rc.1 actually, so you could use that now, if you don’t want to build from source.

1 Like

From the Docs: “If yours does not, feel free to borrow from this and customize it as needed instead of using the php_fastcgi shortcut.”. Which clearly says: ‘Copy, Paste, Customize and you are fine.’

I don’t want to fight you, but in my opinion, the docs should be clearer then.

Time to place a note in the docs, don’t you think? It’s always bad to leave others in the unknown.

It’s not the first time I’m dealing with unclear Docs in caddy. (with things which will mostly work in v2.2 I guess) Searching for an answer to another issue and just getting more issues because the examples don’t even work. These are hours of work I had for a webserver which claims to be fast, easy, and user-friendly.
And at some point everyone gets mad. Caddy took way more time than it should to setup.
And just this little issue took me 2-3 hours instead of 5 minutes! Why? Because of a missing note in the docs and unclear docs for the route directive too (take the example which isn’t one).
So, I’m very sorry for you. But if no-one is gonna say it, someone has to.

I’m done, good night. this ridiculous small hotfix I had to do killed my sleep time.

edit.: From now on I’ll never expect the caddy docs to be correct. :expressionless:

Look, I understand you’re frustrated, but it’s unfair to take out that frustration on us.

We’re doing our best with the limited resources we have. We’re human. We’re not perfect.

It’s just the reality of software development. Things are in constant flux. Believe that we’re doing the best we can.

You’re right to point out those mistakes, and we’ll work to fix them, but it doesn’t help anyone to get frustrated.

1 Like