I’m looking to get caddy setup as a reasonably easy reverse proxy, I was referred here by #nginx on freenode.net because NGINX configs seem twitchy. There aren’t enough examples in the NGINX documentation and I’m finding a few places that could use examples here as well. My usage case may not require what I’m asking for clarification on but I noticed that under Automatic HTTPS - Caddy there is mention near the Enabling the DNS Challenge section there is mention of setting environment variables. Then a snippet of code that looks like the following.
tls {
dns provider
}
Then it mentions, Replace “provider” with the name of your DNS provider (in the table below).You will also need to set environment variables with your account credentials:
The example is lacking any suggestion to how that would look in a Caddyfile which is somewhat frustrating. Because ideally, you would show a working example, not a partial example. As an example is supposed to show you how it works not part of how it works.
So far this instruction tells me to do something like this.
CLOUDFLARE_EMAIL=example@email.com
CLOUDFLARE_API_KEY=SDFSFDSOMEGOBBLDYGOOK@#$#
tls {
dns cloudflare
}
I really have no idea if this is remotely accurate without trying it which I have no problem doing but it seems that this is intended to be targeted at beginners.
This isn’t a Caddy issue, just something I would expect people to know about their computers when they try to use Caddy in advanced ways for advanced infrastructure scenarios. Most people don’t need to use the DNS challenge, auto HTTPS just works.
@matt thanks for your response,
That makes sense and it’s basically what I would have assumed as someone who knows Linux fairly well. If this software is intended for people who aren’t generally seasoned experts it would definitely benefit from having this information in the guide.
I disagree you have to be a seasoned expert to know what environment variables are. It’s not my job to document how to use every platform that Caddy runs on – only to document Caddy. There’s no way I can maintain docs of the magnitude you’re suggesting.
If you find Caddy’s docs aren’t clear enough in specifying that these are OS environmental variables (as opposed to additional Caddyfile configuration), that’s one thing.
But after making it clear that environmental variables are required, I don’t find it unreasonable in the slightest to expect someone working on editable text configuration for a web server to understand what they are and how they relate to their OS of choice.
You’re both not wrong, I actually agree with you on these points about this. This said I’m a big fan of documentation like ArchLinux’s documentation and Docker’s where they always explain fully all relevant steps. It’s definitely not the responsibility of the developers to do this but it definitely does help adoption. I’m fine with it residing on the forums but it just seems incomplete.
The Environment Variables thing doesn’t really need a large change if any at all but you have to keep in mind that marketed towards bloggers and people who just want a web server you might run into a lot of people who will know none of this stuff.
Thanks again for your time and attention to this topic.
