caddyserver / website Goto Github PK

Minor quibble, would there be any interest in addressing this a little?

Including an .editorconfig file for example is an easy way to document some basic style conventions and some editors will automatically recognize and respect those rules without a contributor needing to think about it, potentially reducing some review noise.

We could also add some automated linting/corrections. The Gatsby project runs a pre-commit git hook so that style conventions are applied before publishing/pushing commits for a PR.

As this project is documentation/prose focused, textlint may also be of interest. Although I wouldn't automate the suggested corrections, but some are pretty nice, you can try with markdown content in their online playground to see what it spots.

We could automate with Github Actions and leverage something like reviewdog, they have a recent beta action action-suggester, which allows for reporting the changes on a PR with commit suggestions to selectively apply or discuss. That might be helpful with PR reviews?

Extending caddy examples uses wrong imports:

"github.com/caddyserver/caddy/v2"
"github.com/caddyserver/caddy/v2/caddyconfig/caddyfile"
"github.com/caddyserver/caddy/v2/caddyconfig/httpcaddyfile"
"github.com/caddyserver/caddy/v2/modules/caddyhttp"

Hello,

I just figured out that the documentation has a minor issue:
It says

reverse_proxy localhost:9000 {
	header_up Host {http.reverse_proxy.upstream.hostport}
}

while

reverse_proxy localhost:9000 {
	header_up Host {http.reverse_proxy.upstream.host}
}

would be correct.
As caddy's log entries (level = deug) do not contain the host header actually sent to the upstream, this might cause confusion (and time loss) as it did for me. :-)

I wanted to push a branch to open a pull request but I lack the rights.

From https://caddyserver.com/docs/caddyfile/directives/file_server:

<template_file> is an optional custom template file to use for directory listings. Defaults to the template that can be found here in the source code. Browse templates can use actions from the standard templates module as well.

That first link is dead. I'd submit a fix, but I can't figure out what the link was changed to.

When I navigate to https://caddyserver.com/docs/json/apps/servers/tls_connection_policies/ the main content is empty.

Looking at the requests the page is making, I noticed a 502 to https://caddyserver.com/api/docs/config/apps/servers/tls_connection_policies/

The OriginalReq template data is not documented in https://caddyserver.com/docs/modules/http.handlers.templates

Migrating from v1 to v2 Caddyfile here. I might be dense, but it took me a while to get caddy to just serve my index.html file. I needed file_server as well as root. I eventually had success with this configuration:

coleman.codes {
    root * /opt/blog/public
    file_server
}

You might consider linking to the file_server directive from the root directive's docs page, or perhaps providing an example that combines both on both pages.

The very last example on this page. Reads:

header Cache-Control max=age=3600
But should be (- not = between max and age):
header Cache-Control max-age=3600

I initially opened an issue in the main Caddy repo: caddyserver/caddy#3541
Competing solutions provide docs on different approaches to deploying reverse proxied services with minimal downtime. I believe it is in Caddy's best interest to do the same. I am willing to write these docs if someone explains the current state of affairs.

Original description follows:
So, let's assume I am using Caddy to reverse proxy to a Go app running on port 2490. I want to start a new version of the application, make it serve new requests, then when the old version drains (no requests served), shut it down.
I am assuming the following steps:

• Start new version of the application on a new port.
• Add a new upstream to the config file, and tell Caddy to reload it.
• Send a shutdown signal to the old version of the application. Once the current requests are done, it will shut down and
  make the health check fail.
• Remove the old version from the config file.

Is this the optimal way to do this? If yes, how do I tell Caddy to stop sending new requests to the old application, once the new one is up? Is there a lb_policy that can help me here? Would it make sense to first drain the old app, and then start sending traffic to the new one, risking small downtime but gaining easier db handling (== safe to run migrations)? If so, is there a way to do that? Maybe by always using a single upstream and a single config refresh (new app starts => Caddy config is updated to point to it. Old app is done once it's done)?

@francislavoie indicated that SRV DNS is a good way to avoid config refreshes, but I am personally not against a config refresh, especially if it allows me to avoid running another service for discovery purposes.

I had a caddyfile that roughly did the following:

example.com {
	reverse_proxy [...]
	log {
		output file /var/log/caddy/example.com.log
	}
}

example.com/subdir {
	reverse_proxy [other endpoint]
	log {
		output file /var/log/caddy/example.com-subdir.log
	}
}

But everything got logged to the file of the first site block (regardless of ordering, its always the most general block). This does not seem to be a bug but more of a missing feature so far (I found e.g. caddyserver/caddy#3418), so it would be nice if this would be documented better.

I'm not sure on the wording and where to best put it or I would have opened a small PR myself. But as a reader, I would expect it to be mentioned on the page for the log directive at least.

Thank you!

hi! I noticed that https://caddyserver.com/docs/json/apps/http/ is now empty (and I think I remember it used to not be empty)

hi, I have a third party module want to add to docs, but only found standard module here. Where should I put my module docs, thanks

https://caddyserver.com/docs/caddyfile-tutorial has the old syntax for env vars {$SITE_ADDRESS}, which doesn't work in v2. Change to {env.SITE_ADDRESS}.

The URL in install.md https://dl.cloudsmith.io/public/caddy/stable/cfg/gpg/gpg.155B6D79CA56EA34.key returns 404.
The URL https://dl.cloudsmith.io/public/caddy/stable/gpg.155B6D79CA56EA34.key on the cloudsmith website works fine.
Perhaps this can be updated?

Update documentation so it's noted that x-forwarded-for header is used for remote_ip.

Closed in #94

The information in this article is really useful for users of Caddy to figure out how route and handle work: https://caddy.community/t/composing-in-the-caddyfile/8291. Consider incorporating the information in it into the official documentation.

Hello,
I'm the author of a Caddy module that is listed on the official download page: https://github.com/porech/caddy-maxmind-geolocation

However, unlike the other plugins, the documentation is not appearing. When I first submitted the module, the documentation was not there; however after adding it I tried rescanning and even removing the package and submitting it again, but no luck.

Is this something wrong on my repo, or is it a parsing issue?

Thanks!

I get the NET::ERR_CERT_COMMON_NAME_INVALID exception in Chrome and in firefox the exception is
Error code: SSL_ERROR_BAD_CERT_DOMAIN

I am not sure if this is the right place to report it. However, this will impact all caddy v1 download scripts. Is caddy v1 no longer available for download from sites?

2020/07/23 18:39:15.870 ERROR  http.log.error  template: /docs/index.html:4:20: executing "/docs/index.html" at <include $markdownFilePath>: error calling include: open src\docs\markd
own\install\.md: The system cannot find the path specified.     {"request": {"method": "GET", "uri": "/docs/install/", "proto": "HTTP/1.1", "remote_addr": "[::1]:54320", "host": "localhost:2015", "headers": {"User-Agent": ["Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:79.0) Gecko/20100101 Firefox/79.0"], "Accept": ["text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8"], "Accept-Language": ["en-US,en;q=0.5"], "Accept-Encoding": ["gzip, deflate"], "Connection": ["keep-alive"], "Referer": ["http://localhost:2015/docs/"], "Upgrade-Insecure-Requests": 
["1"]}}, "duration": 0.0030252, "status": 500, "err_id": "tp3q5fbby", "err_trace": "templates.(*Templates).executeTemplate (templates.go:305)"}

It appears that when it tries to load the markdown file, it loads most of the url correctly, but puts a / right before the markdown extension

Looking into Caddy via Google searches and links from communities including the forum with posts only a month or so old, I have come across v1 doc URLs.

These fail to load as they're no longer hosted. One has to view the documentation section and scroll down to the bottom of the left sidebar to get a download link of the v1 docs archived.. I feel that was too soon. Even though I'm only interested in using v2, the current docs have been hit/miss on quality at presenting information. Some v1 docs also have no equivalent v2 yet until the feature is ported, while v1 may no longer be actively supported, I assume there are still users running v1.

Hosting v1 docs shouldn't be that much of a burden, although I'd advised a warning banner at the top of the pages to clearly communicate to users that these are v1 docs and they might want to access the v2 docs instead.

Alternatively, rather than fail, these routes should be captured and redirect to a v1 deprecation page that encourages adoption of v2 while providing a link to the v1 docs archive if hosting them is an issue. Not doing this, Google and any other indexers should be informed appropriately that this content is no longer available so they remove their indexes on it sooner?

The default format for logs is listed as console here: https://caddyserver.com/docs/caddyfile/directives/log#format-modules

However, if a consumer does not provide a format, the default is actually json.

https://caddyserver.com/docs/modules/

Hi @mholt,

thanks for caddy — it's a terrific project and I use it a lot.

I noticed that I cannot select Hetzner as a DNS provider from the caddy download page. The implementation under github.com/caddy-dns/hetzner seems complete and on par with e.g. github.com/caddy-dns/gandi (which in turn is available from the download section).

I see that your download page calls https://caddyserver.com/api/packages, but that api does not include the hetzner module.

Is this, where the website's Account feature comes in? Do I have to create an account and add the hetzner dns module, so it gets displayed via the https://caddyserver.com/api/packages api?

Thanks in advance
Denis Brodbeck

At /docs/markdown/download.md the section for Debian, Ubuntu, Raspbian only says:

Installing this package automatically starts and runs Caddy for you.

But it does not describe which unit file is used (there are two...) or how to query its systemd status.

I wish it would say something like (hypothetically):

Installing this package automatically starts and runs Caddy for you.

It runs as the caddy-api user systemd unit, and you can check its status with systemctl status caddy-api

(This kind of wording wouldn't be terrible to document for the other options too.)

I ended up killing the caddy process with sudo and redefining the systemd unit file myself because I couldn't figure out how to query its status from the OS. (Yep it's a mess... I'll clean it tomorrow.)

Hello! I followed a (probably outdated) link from an old issue to https://caddyserver.com/docs/faq and got back an HTTP 500. Assuming the page doesn't exist anymore, the response needs to be fixed to be a 404.

I registered a plugin the other day. Since then I made an update and shipped a new version - one that changed the comments on the handler struct that shows the a description of the package on the downloads page.

I hit the "rescan" button, It reported it rescanned (immediately I might add, which seemed suspicious.) However, the description of the package that come from those comments have not been updated. So it appears to me the reason feature is broken.

Hi, first off, amazing work getting v2 up and running with the same simplicity and fundamentals of v1. Piece of art 👏.

V1 website docs was a pleasant reading.
I can see some comparison with the colour scheme choice for v2 docs from Docker documentation (which for instance can be switched on/off).

Just did a really quick change using the colours from Caddy website and I believe this gives the reader a better reading experience - I'm not a designer, some colours might be better applied.

Happy to provide a PR.

Best.

Might be, that I make a lot of mistakes here, but this seems like your documentation is outdated?

I was trying out auto_https global opt on a v2.0 container

But it kept failing with unrecognized parameter name: auto_https.

According to caddyserver/caddy#3219 (comment) this is v2.1 only

It would be nice to have such info available in the docs.

After the last website upgrade the json doc section is not working as expected: clicking on https://caddyserver.com/docs/json/ give an empty page, same thing accessing the direct links like https://caddyserver.com/docs/modules/http.reverse_proxy.transport.http

Just a heads up. Looks like wget works with the permanent redirect on HTTP, so must be HTTPS only. Problem persists in safari and chrome on macOS 10.15.5.

Misconfiguration?

I recently implemented a Caddy module extending the ability of Caddy's standard authentication handler with JWT authentication.

But how can I also contribute to the listing of All Modules on the website?

Not sure if this is the right place to report this. I was trying to "register" my plugin: https://github.com/lindenlab/caddy-s3-proxy

I got the following error:

Sorry, something went wrong:

unable to scan modules in package https://github.com/lindenlab/caddy-s3-proxy

Please include this error ID if reporting:
a5970848-2bf5-43ea-bb0f-5035f71683af

I was going to try and see if I could fork this to make my own module documentation in the same vein as https://caddyserver.com/docs/json/apps/http/servers/routes/handle/authentication/. Looking at the source code, it seems the website does some requests to an API server providing the documentation, but I couldn't find this server's source. Am I looking at the wrong place? Would it be possible to document how we can make our own docs like this one?

This page has a bunch of useful examples: https://caddyserver.com/docs/caddyfile/directives/reverse_proxy

The one that was missing for me was one showing how to configure a reverse proxy such that traffic to a specific subdomain is routed to a specific backend - there's a path one but not one for a specific subdomain.

Hey folks,

As I investigated if Caddy supported custom resolvers, I found that the feature is in but there's no mention of it in the docs.

caddyserver/caddy#3479

I guess the priority of this issue might be low. It's OK to fix it at your convenience.

$ curl -o /dev/null -v https://caddyserver.com/
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
*   Trying 138.68.240.78:443...
* TCP_NODELAY set
*   Trying 2604:a880:2:d0::1145:e001:443...
* TCP_NODELAY set
  0     0    0     0    0     0      0      0 --:--:--  0:00:07 --:--:--     0
* Connected to caddyserver.com (138.68.240.78) port 443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* successfully set certificate verify locations:
*   CAfile: none
  CApath: /etc/ssl/certs
} [5 bytes data]
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
} [512 bytes data]
  0     0    0     0    0     0      0      0 --:--:--  0:00:09 --:--:--     0
* TLSv1.3 (IN), TLS handshake, Server hello (2):
{ [122 bytes data]
* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
{ [15 bytes data]
* TLSv1.3 (IN), TLS handshake, Certificate (11):
{ [2561 bytes data]
  0     0    0     0    0     0      0      0 --:--:--  0:00:10 --:--:--     0
* TLSv1.3 (IN), TLS handshake, CERT verify (15):
{ [264 bytes data]
* TLSv1.3 (IN), TLS handshake, Finished (20):
{ [36 bytes data]
* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
} [1 bytes data]
* TLSv1.3 (OUT), TLS handshake, Finished (20):
} [36 bytes data]
* SSL connection using TLSv1.3 / TLS_AES_128_GCM_SHA256
* ALPN, server accepted to use h2
* Server certificate:
*  subject: CN=caddyserver.com
*  start date: Jan  2 15:39:01 2020 GMT
*  expire date: Apr  1 15:39:01 2020 GMT
*  subjectAltName: host "caddyserver.com" matched cert's "caddyserver.com"
*  issuer: C=US; O=Let's Encrypt; CN=Let's Encrypt Authority X3
*  SSL certificate verify ok.
  0     0    0     0    0     0      0      0 --:--:--  0:00:11 --:--:--     0
* Using HTTP2, server supports multi-use
* Connection state changed (HTTP/2 confirmed)
* Copying HTTP/2 data in stream buffer to connection buffer after upgrade: len=0
} [5 bytes data]
* Using Stream ID: 1 (easy handle 0x7fffe4c33f90)
} [5 bytes data]
> GET / HTTP/2
> Host: caddyserver.com
> user-agent: curl/7.67.0
> accept: */*
>
{ [5 bytes data]
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
{ [130 bytes data]
  0     0    0     0    0     0      0      0 --:--:--  0:00:13 --:--:--     0
* Connection state changed (MAX_CONCURRENT_STREAMS == 250)!
} [5 bytes data]
< HTTP/2 200
< content-type: text/html; charset=utf-8
< date: Mon, 03 Feb 2020 10:26:17 GMT
< referrer-policy: no-referrer-when-downgrade
< server: Caddy
< server: Caddy
< strict-transport-security: max-age=31536000
< x-content-type-options: nosniff
< x-frame-options: SAMEORIGIN
< x-xss-protection: 1; mode=block
< content-length: 34543
<
{ [5 bytes data]
 90 34543   90 31145    0     0    205      0  0:02:48  0:02:31  0:00:17     0
^C

When you go to the documentation on the website, and go to 'JSON config structure', every page loads very slow. I already have this problem for over a month, I thought it would be a temporary issue, so I never reported it.

Example:
Visit https://caddyserver.com/docs/json/apps/http/ in any browser

I have tried on MacOS 11.4, on Safari 14.1.1 or latest Chrome / Firefox.

If you check the network tab in the developer tools, you can see that the following request is blocked for almost 10 seconds:
https://caddyserver.com/api/docs/config/apps/http/

So this is probably a server / config related issue.

I am investigating an issue with an architecture that involves the Caddy server. While investigating, I noticed that what I experience could be explained by the default value set for fail_duration with passive health checks configuration:

https://caddyserver.com/docs/caddyfile/directives/reverse_proxy#passive-health-checks

What is the default value for this option? where are default values defined?

It would be helpful to add it to the docs (similarly to max_fails) or to mention somewhere where to find default values.

PS: the option max_fails mentions fail_timeout but I guess this is fail_duration.

Bug: v1 documentation will be removed "soon".

Expected behavior: Documentation is permanently available. Failing that, availability should be predictable.

Fix: Remove scare banner from documentation pages, failing that, add a date so that users will have a firmer call-to-action to make a local copy.

In https://caddyserver.com/docs/quick-starts/reverse-proxy

Document --change-host-header option. This option is frequently used when the upstream server requires correct Host header.

Hi, I am not sure of the best way to put this...
I see there is no LICENSE file, and I would guess that is by design,
I can understand why the team wouldn't want people to use everything in this repo as-is for other projects.

But, I have been thinking about this a few weeks, and this repo does something very very special that might be worth figuring out how to share:

This repo shows how to build a first-class website without using a static site generator, and instead using Caddy. For example having a 'docs' section using markdown and Caddy is pretty awesome without having to get a static generator involved.

I think this repo uses hand-crafted CSS and not Bootstrap or Tailwind, which would really best suit my needs, but I think it is worth pointing out that a first-class website template like this using, say, Tailwind with a permissive license might really help a lot of people adopt Caddy instead of a static site.

So, maybe there is a way to add a license that allows people to build from this example without hurting the Caddy project in some way?

I also think maybe a site or project for "Caddy themes" or "Caddy templates" could be a really awesome way to show the power of using Caddy INSTEAD of a static site generator.

This is one way I would like to use Caddy, but would really be helped by permissive license examples using either Bootstrap or Tailwind.

Thanks for making Caddy!

Perhaps I'm missing something, because this feels like an issue which would have been caught/reported instantly, but the page at https://caddyserver.com/download appears to have no functionality at all other than downloading a single linux/amd64 binary despite many more options being seemingly available. I've found the following issues:

• Platform selection box does nothing. The button always downloads caddy_linux_amd64.
• Modules/plugins cannot be selected at all.
• The search box does nothing.

These make the entire page effectively a download button, because all other functionality is unavailable.

I'm on openSUSE Tumbleweed with Brave Browser 1.28.105 (Chromium: 92.0.4515.131).

So i am going through and rebuilding the docs-nav.html embed in markdown, and so far it is going Very good as the generated HTML lines up near perfectly with the css used! Aside from the catagory titles, however it does work,

< /src/includes/docs-nav.md >

- [Welcome](/docs/)
- [Wiki 🔗](https://caddy.community/c/wiki/13)

#### Get Caddy
- [Download](/docs/download/)
- [Build from Source](/docs/build/)
- [Install](/docs/install/)

#### Tutorials
- [Getting Started](/docs/getting-started/)
- [Quick Starts](/docs/quick-starts/)
    - [Using the API](docs/quick-starts/api)

<!-- /src/includes/docs-nav.html -->
{{$markdownFilename := default "docs-nav"}}
{{$markdownFilePath := printf "/includes/docs-nav.md"}}
{{$markdownFile := (include $markdownFilePath | splitFrontMatter)}}
{{$title := default $markdownFilename $markdownFile.Meta.title}}
<nav class="sidebar">
	{{markdown $markdownFile.Body}}
</nav>

generates as so, which is close enough to not affect users

Hey there!

I'd like to report a security issue but cannot find contact instructions on your repository.

If not a hassle, might you kindly add a SECURITY.md file with an email, or another contact method? GitHub recommends this best practice to ensure security issues are responsibly disclosed, and it would serve as a simple instruction for security researchers in the future.

Thank you for your consideration, and I look forward to hearing from you!

(cc @huntr-helper)

Where to place the @caddy.json? In the same folder, in which I run the command?
And why @?

https://caddyserver.com/docs/getting-started

Per the doc for access logs:

output configures a where to write the logs to.

If I am not mistaken, maybe the above description should be changed to:

output configures where to write the logs.

Hello,

I'm currently getting an unhandled 500 from this incorrect URL:
https://caddyserver.com/docs/caddyfile/directives/errors

Please close if this issue is resolved by the time you read my message 😎

https://caddyserver.com/docs/caddyfile/directives/tls

<cert_file> and <key_file> are the paths to the certificate and private key PEM files. Specifying just one is invalid; specifying both will disable automatic HTTPS.

• Does not disable automatic HTTPS
• Using the JSON API for ignore_loaded_certificates: false does not disable either (assuming this is manually loading)
• Differs from tls internal with auto_https off as the certificate is still provided.

Caddyfile:

{
  #local_certs
  #auto_https disable_redirects
}

192.168.1.42:8000, example.localhost:8000 {
  #tls internal
  tls /tls/example.localhost-cert.pem /tls/example.localhost-key.pem
  reverse_proxy localhost:9000

  # Unrelated to reverse_proxy, same behavior:
  #root * /usr/share/caddy
  #file_server
}

• Providing my own cert and key PEM files is working as expected.
• Visiting http://example.localhost will redirect to https://example.localhost:8000, which should not happen if auto_https is disabled?
• auto_https either configured to off or disable_redirects work as intended. Just auto_https is implicitly enabled otherwise.

Initially seemed that auto_https config had no effect, but was due to 301 redirects previously issued, tested again in Chrome Incognito (closed session after each config change), which confirms the findings above.

Do these docs need to be corrected?