7 ms·

Caddy has a lot of great features, but (at least as of last year) Nginx has the edge on documentation. Caddy’s docs were almost useless. Hopefully they’ve impro

by zja 3y ago

Caddy has a lot of great features, but (at least as of last year) Nginx has the edge on documentation. Caddy’s docs were almost useless. Hopefully they’ve improved since I last used it.

nixcraft 3y ago
Caddy cannot be found in the default repositories of Debian or RHEL. This raises the question of why one would use such a server. Personally, I am hesitant to download a random pre-built executable from Github, even if it is open source. I would much rather use the apt or dnf version, as anything else seems like just another toy server.
- garbagecoder 3y ago
  Just build it from source?
  - 5e92cb50239222b 3y ago
    And then watch it like a hawk for vulnerabilities and rebuild as needed. No thanks.
- jakebasile 3y ago
  Caddy provides their own yum repo and I'm pretty sure it's in EPEL too.
- cpuguy83 3y ago
  While it is convenient to have software prebuilt in a trusted repo, these repos are more about providing toolchains. If something isn't in the repo (or the repo, as it often is, ie out of date) use the toolchain to build what you want.
- xeeeeeeeeeeenu 3y ago
  >Caddy cannot be found in the default repositories of Debian or RHEL. Debian 12 (bookworm) will have it: https://packages.debian.org/bookworm/caddy https://packages.debian.org/bookworm/caddy
  - francislavoie 3y ago
    FWIW, that was created by someone not affiliated with the Caddy project, and looks to no longer be maintained (latest is v2.6.4, but it has v2.6.2). So as a maintainer of Caddy, I cannot recommend using that repo.
    - peppermint_gum 3y ago
      This is the official Debian repository. The package versions are frozen in each major Debian release. However, they may backport security and bug fixes. In practice, in the case of less popular packages, they do this on demand, when someone requests it in the bug tracker.
      - francislavoie 3y ago
        Well, users should know that if they report issues while using releases from that source, we can't reasonably help them, and that they should use an official release to get bug and security fixes promptly. I want to emphasize that we have no contact at all with the people maintaining that Debian package, they've never reached out to discuss anything. We're absolutely open to that (and they know where to find us, not hard to contact us either on GitHub, Twitter, our forums, here, etc).
        5e92cb50239222b 3y ago
        It's exactly the same way tens of thousands of other packages have been shipped for decades, including many other web servers like nginx, httpd, lighttpd. No need to paint so much drama over this. They will contact you if the need arises. It's the same usual process that has been used since the 90s to great success.
        francislavoie 3y ago
        Users will reach out to us first, not to debian, because we're easier to reach for help (via social or our forums). If they tell us they're using an outdated version which doesn't have the fix for what they need, I have no other choice but to tell them to stop using the debian-maintained package, and use our officially maintained package.
- francislavoie 3y ago
  Debian's requirements for packaging of Go software is unreasonable. They expect every single dependency to be individually packaged. The total dependency chain of Caddy ends up being massive. We (the Caddy maintainers) don't have time necessary to allocate to a single distribution, to package and maintain every single dependency individually when all we want to do is ship a single static binary (plus some support files). Instead, we ship with our own debian repo, hosting graciously provided by CloudSmith https://caddyserver.com/docs/install#debian-ubuntu-raspbian https://caddyserver.com/docs/install#debian-ubuntu-raspbian. This is packaged via CD with GitHub Actions, and you can verify the authenticity of the build since it's signed by Matt Holt's GPG key. For RHEL, it's in COPR, and that's the best you'll ever get for similar reasons https://copr.fedorainfracloud.org/coprs/g/caddy/caddy/ https://copr.fedorainfracloud.org/coprs/g/caddy/caddy/
  - m_sahaf 3y ago
    Adding to Francis input, the release artifacts (not the .deb packages, which are signed with Matt's key) published on GitHub are authenticated with Sigstore tooling[0]. You can verify the artifacts and the .deb packages were not tampered to the byte! The builds are reproducible and verifiable. FUD doesn't have any room to loiter. You can also build it from source using the `buildable` source archive artifact that includes all the deps so it can be built in air-gapped machine. Like its sibling artifacts, the source archive is signed, the signature is published, the signing certificate is available, and the checksum is published and also signed. What's so concerning? [Disclaimer: Affiliated with Caddy] [0] https://www.sigstore.dev/how-it-works https://www.sigstore.dev/how-it-works
  - mardifoufs 3y ago
    What's the reasoning behind that packaging requirement on Debian? Thanks for working on caddy by the way! I find it very neat.
    - francislavoie 3y ago
      Honestly, I don't understand it fully. I just know the barrier-to-entry is too high for us to spend time on it. We don't have contact with any debian packaging maintainers that would be willing to work with us. But https://go-team.pages.debian.net/packaging.html https://go-team.pages.debian.net/packaging.html is one of my main resources for my understanding of their requirements. And that goes without saying that Debian in general tends to release much slower than we'd be comfortable with. We don't want users running outdated and potentially insecure versions of Caddy. Best if users keep up to date by using a first-party installation method where we have control over the distribution pipeline.
mattbee 3y ago
The docs were brilliant for v1, it wouldn't surprise me if they were the spec for a great user experience and the code came second. Despite v2 supporting a very similar config file, the documentation doesn't emphasise that and tries to steer you towards its API, confusing JSON config syntax etc. It's still a very good web server for very few lines of config, but I don't relish trying to learn something new from its docs like I used to.
- withinboredom 3y ago
  It's almost like the docs were written for someone upgrading from V1 (or familiar with V1) instead of a newcomer who knows nothing (like the V1 docs were written for).
  - francislavoie 3y ago
    That's not true. The docs are written with the expectation that the user understands how the web works. We can't reasonably teach that in our docs. Instead, users should read MDN for that stuff. If you were coming from v1, the only page that makes that assumption is the upgrade guide https://caddyserver.com/docs/v2-upgrade https://caddyserver.com/docs/v2-upgrade. Everything else is either a getting started guide, a tutorial, or reference docs for Caddyfile and JSON config.
    - withinboredom 3y ago
      I didn't say it was true, I said it just seems like it. As an example: https://caddyserver.com/docs/caddyfile/directives/php_fastcgi https://caddyserver.com/docs/caddyfile/directives/php_fastcg... -- it shows the syntax, but nowhere on the page does it tell you WHERE to put it in the config file. Is it top-level? Do I nest it in something else? Keep in mind, most people are starting with a mostly blank file, and zero context about how Caddy works (whether or not they understand how the web works). This page won't answer the basic questions of where it is allowed, and neither will the getting-started docs, which tells you to make a json file instead of a Caddyfile but the docs for the thing I looked up doesn't look like json (maybe I know this, maybe I don't). It's all very confusing for someone looking in the docs for a solution and instead has to learn how everything works, whether they want to or not.
KomoD 3y ago
Couldn't agree more, I absolutely LOVE Caddy, but the docs were truly awful the last time I had to look, all forums, etc also referenced v1 a lot which was really frustrating.
- mholt 3y ago
  I think we've improved them a lot since then. A new website is in the works which should improve them even more.

by zja 3y ago

Caddy has a lot of great features, but (at least as of last year) Nginx has the edge on documentation. Caddy’s docs were almost useless. Hopefully they’ve improved since I last used it.

nixcraft 3y ago

Caddy cannot be found in the default repositories of Debian or RHEL. This raises the question of why one would use such a server. Personally, I am hesitant to download a random pre-built executable from Github, even if it is open source. I would much rather use the apt or dnf version, as anything else seems like just another toy server.

garbagecoder 3y ago
Just build it from source?
- 5e92cb50239222b 3y ago
  And then watch it like a hawk for vulnerabilities and rebuild as needed. No thanks.
jakebasile 3y ago
Caddy provides their own yum repo and I'm pretty sure it's in EPEL too.
cpuguy83 3y ago
While it is convenient to have software prebuilt in a trusted repo, these repos are more about providing toolchains. If something isn't in the repo (or the repo, as it often is, ie out of date) use the toolchain to build what you want.
xeeeeeeeeeeenu 3y ago
>Caddy cannot be found in the default repositories of Debian or RHEL. Debian 12 (bookworm) will have it: https://packages.debian.org/bookworm/caddy https://packages.debian.org/bookworm/caddy
- francislavoie 3y ago
  FWIW, that was created by someone not affiliated with the Caddy project, and looks to no longer be maintained (latest is v2.6.4, but it has v2.6.2). So as a maintainer of Caddy, I cannot recommend using that repo.
  - peppermint_gum 3y ago
    This is the official Debian repository. The package versions are frozen in each major Debian release. However, they may backport security and bug fixes. In practice, in the case of less popular packages, they do this on demand, when someone requests it in the bug tracker.
    - francislavoie 3y ago
      Well, users should know that if they report issues while using releases from that source, we can't reasonably help them, and that they should use an official release to get bug and security fixes promptly. I want to emphasize that we have no contact at all with the people maintaining that Debian package, they've never reached out to discuss anything. We're absolutely open to that (and they know where to find us, not hard to contact us either on GitHub, Twitter, our forums, here, etc).
      - 5e92cb50239222b 3y ago
        It's exactly the same way tens of thousands of other packages have been shipped for decades, including many other web servers like nginx, httpd, lighttpd. No need to paint so much drama over this. They will contact you if the need arises. It's the same usual process that has been used since the 90s to great success.
        francislavoie 3y ago
        Users will reach out to us first, not to debian, because we're easier to reach for help (via social or our forums). If they tell us they're using an outdated version which doesn't have the fix for what they need, I have no other choice but to tell them to stop using the debian-maintained package, and use our officially maintained package.
francislavoie 3y ago
Debian's requirements for packaging of Go software is unreasonable. They expect every single dependency to be individually packaged. The total dependency chain of Caddy ends up being massive. We (the Caddy maintainers) don't have time necessary to allocate to a single distribution, to package and maintain every single dependency individually when all we want to do is ship a single static binary (plus some support files). Instead, we ship with our own debian repo, hosting graciously provided by CloudSmith https://caddyserver.com/docs/install#debian-ubuntu-raspbian https://caddyserver.com/docs/install#debian-ubuntu-raspbian. This is packaged via CD with GitHub Actions, and you can verify the authenticity of the build since it's signed by Matt Holt's GPG key. For RHEL, it's in COPR, and that's the best you'll ever get for similar reasons https://copr.fedorainfracloud.org/coprs/g/caddy/caddy/ https://copr.fedorainfracloud.org/coprs/g/caddy/caddy/
- m_sahaf 3y ago
  Adding to Francis input, the release artifacts (not the .deb packages, which are signed with Matt's key) published on GitHub are authenticated with Sigstore tooling[0]. You can verify the artifacts and the .deb packages were not tampered to the byte! The builds are reproducible and verifiable. FUD doesn't have any room to loiter. You can also build it from source using the `buildable` source archive artifact that includes all the deps so it can be built in air-gapped machine. Like its sibling artifacts, the source archive is signed, the signature is published, the signing certificate is available, and the checksum is published and also signed. What's so concerning? [Disclaimer: Affiliated with Caddy] [0] https://www.sigstore.dev/how-it-works https://www.sigstore.dev/how-it-works
- mardifoufs 3y ago
  What's the reasoning behind that packaging requirement on Debian? Thanks for working on caddy by the way! I find it very neat.
  - francislavoie 3y ago
    Honestly, I don't understand it fully. I just know the barrier-to-entry is too high for us to spend time on it. We don't have contact with any debian packaging maintainers that would be willing to work with us. But https://go-team.pages.debian.net/packaging.html https://go-team.pages.debian.net/packaging.html is one of my main resources for my understanding of their requirements. And that goes without saying that Debian in general tends to release much slower than we'd be comfortable with. We don't want users running outdated and potentially insecure versions of Caddy. Best if users keep up to date by using a first-party installation method where we have control over the distribution pipeline.

mattbee 3y ago

The docs were brilliant for v1, it wouldn't surprise me if they were the spec for a great user experience and the code came second. Despite v2 supporting a very similar config file, the documentation doesn't emphasise that and tries to steer you towards its API, confusing JSON config syntax etc. It's still a very good web server for very few lines of config, but I don't relish trying to learn something new from its docs like I used to.

withinboredom 3y ago
It's almost like the docs were written for someone upgrading from V1 (or familiar with V1) instead of a newcomer who knows nothing (like the V1 docs were written for).
- francislavoie 3y ago
  That's not true. The docs are written with the expectation that the user understands how the web works. We can't reasonably teach that in our docs. Instead, users should read MDN for that stuff. If you were coming from v1, the only page that makes that assumption is the upgrade guide https://caddyserver.com/docs/v2-upgrade https://caddyserver.com/docs/v2-upgrade. Everything else is either a getting started guide, a tutorial, or reference docs for Caddyfile and JSON config.
  - withinboredom 3y ago
    I didn't say it was true, I said it just seems like it. As an example: https://caddyserver.com/docs/caddyfile/directives/php_fastcgi https://caddyserver.com/docs/caddyfile/directives/php_fastcg... -- it shows the syntax, but nowhere on the page does it tell you WHERE to put it in the config file. Is it top-level? Do I nest it in something else? Keep in mind, most people are starting with a mostly blank file, and zero context about how Caddy works (whether or not they understand how the web works). This page won't answer the basic questions of where it is allowed, and neither will the getting-started docs, which tells you to make a json file instead of a Caddyfile but the docs for the thing I looked up doesn't look like json (maybe I know this, maybe I don't). It's all very confusing for someone looking in the docs for a solution and instead has to learn how everything works, whether they want to or not.

KomoD 3y ago

Couldn't agree more, I absolutely LOVE Caddy, but the docs were truly awful the last time I had to look, all forums, etc also referenced v1 a lot which was really frustrating.

mholt 3y ago
I think we've improved them a lot since then. A new website is in the works which should improve them even more.