How to get help with Caddy more effectively

Site Feedback
1

Hi all,

Here are some tips to help you get help when you need help. :slight_smile:

0. Try giving help first

Not only does answering someone else’s question give you fake Internet points, it also helps you learn a lot in the process! There’s true satisfaction that comes from spending a few minutes to dive into a question or problem and lasting knowledge that you can get in no other way.

1. Ask questions in the forum (this place)

We try to keep the issue tracker for actionable development issues only, and the forum is better suited for asking and answering questions about how to use Caddy or for help figuring out a configuration.

2. PLEASE DON’T REDACT YOUR CADDYFILE OR LOGS (except credentials)

The single most common reason that helping is difficult and takes longer is because people don’t tell us the truth. And what I mean by that is that they change or remove things before posting them into the forum. This makes troubleshooting much slower and more frustrating for everyone. Often, redaction is done incorrectly or inconsistently so that the redaction is not representative of the actual truth and thus is misleading. Here’s just one example where redaction caused delays and frustration.

So: except for removing secret credentials, please don’t change your Caddyfile or logs when posting them. This is now a forum rule because it is so problematic.

But wait! We can help in private when posting information publicly isn’t an option.

We understand that there are Caddy users who are unable to provide the needed information in public, who do not want to associate their account with their sites in public, or who do not want to rely on community support. We offer private support for sponsors at a level corresponding to your sponsorship tier. Become a sponsor if you would like private support!

Okay – if you can accept this, great! :smiley: Move on to the next item. If you need to be convinced, keep reading.

There are several reasons we have to enforce these rules.

  1. Caddy’s behavior changes based on the actual values you use in your Caddyfile, not merely the syntax of it. (This is one thing that makes Caddy very easy to use, in keeping with the “just works” design goal.)

  2. Often, people make errors when replacing values. Either they do not use proper values from the same input class as the original values, or they do not replace them consistently across all instances of the same value. Sometimes, instances are even skipped or missed, adding to the confusion.

  3. Helpers need to be able to replicate your problem so they can experiment with it and try to find a solution. They can’t do that if you provide fake information or leave out vital pieces of the puzzle.

  4. Interactions between Caddy, web browsers / clients, the network stack, the OS, external resources such as DNS resolvers and CAs, are highly complex no matter how the problem is approached. Changing values in the log or Caddyfile only makes the mud murkier and adds to the huge list of unknown factors.

Many, many of you will be tempted to replace your domain name with something else which you do not own, or will use special characters like * or <foo>, etc, to fill their place. DO NOT DO THIS. We’ve had complaints when Caddy users have taken others’ online properties as examples. And special characters break syntax rules, leaving helpers confused about how that ever worked for you in the first place.

Not only are you not doing yourself any favors by redacting your domain names, you’re making it impossible for us to observe the behavior you’re seeing because we can’t access your site if we don’t know what it is.

You might think you’re keeping a secret, but your domain names are already in public certificate transparency logs (which can even be streamed in near-real-time) when Caddy obtained a TLS certificate for your site. Remember that HTTPS relies on public key infrastructure, which means no secret hostnames. And DNS points that name to your server, so the jig is up anyway.

One of our community moderators @Whitestrake, sums it up nicely in another thread:

While he’s right that example.com/org are acceptable filler domains, there are only two of them, and it’s quite possible that in replacing your actual domain name with these, you will lose some information. For example, are your domains subdomains of other domains that you serve? or of other domains that have certificates from Let’s Encrypt? It matters, you know: Let’s Encrypt rate limits subdomains differently. The technical rules are nuanced, and so is the business of replacing actual values. Just don’t do it. Plus, if you have more than two domains in your Caddyfile, there are obviously not enough example domains to go around (and using subdomains, other variants, or repeating the same name all messes with things, because you’re not recreating the actual problem with high fidelity).

So, removing information from your Caddyfile, logs, and terminal commands not only adds more work for you, it makes troubleshooting anywhere from hard to impossible — to the point where all we can say is something generic, like: “The configuration you’ve provided should not be doing that, and there are no known bugs that would cause it to do so.”

“Wait, I can’t even redact my email address?” you might think. We can bend a little on email addresses, but for your information, specific (invalid or valid) email addresses have sometimes been the cause of an issue! So if you want a quick easy resolution, leave all the information there.

So if you need help but can’t post this stuff publicly, please reach out and we’ll get you set up with private support.

3. Simplify, then fully explain your setup / environment

What’s your OS? Caddy version? What command did you run? Are you running systemd? Do you know how to use systemd? (Even we haven’t figured it out yet.) Is your environment what you think it is? Do you have a firewall set up? Are you SURE? Are you even running the right binary? Did you check permissions? Are you using Docker? It’s always Docker…

Seriously: eliminate as many of these variables as you can when asking for help, or you’ll be asking for trouble. This is your responsibility, please. Some of us won’t even be inclined to help if Docker or systemd is in the picture because of the enormous, unnecessary complexities they add to troubleshooting Caddy issues. They are external and have nothing to do with Caddy, so eliminate them.

Reduce it all down to a simple, repeatable command (and HTTP request, if applicable) when possible. Simplify the Caddyfile all the way until the problem disappears. Then re-insert the part that makes it break. Voila! You’ve just identified where the issue is. State this in your question (if you still have a question).

4. Investigate

Please do as much as you can to solve the problem yourself. Read the documentation. Show some evidence that you’ve done due diligence. Besides, this is more rewarding.

5. Post full error logs/messages

Please please please don’t just say “it crashed” or “it won’t work” or “it breaks” – describe exactly what is going on. Your question may get ignored or closed if it is not helpful. Run Caddy with the -log flag or use the log and errors directives as applicable to obtain as much information as you can. Specific errors are crucial to troubleshooting.

Thank you for reading this post. I hope it will help improve your experience here, and the experiences of others who take time to read your own posts and help you!

5 Likes