Docs should include JSON Examples

[phish108]

I really enjoy working with the caddy admin API, but the documentation is not supportive at all. Currently, I have to submit a full Caddyfile to a test server in order to reverse engineer the logic of the JSON format of the different features.

For some reason the docs emphasise on the Caddyfile format, only. However, it is not possible to push partial Caddyfiles to the API because the admin API accepts only JSON documents. As for many features it is not at all clear where they should go in the JSON format, it would be really helpful to include basic JSON examples, too.

[mholt]

Yeah, I'd like to see more info on JSON docs too, but haven't really had time.

For now, we do have a quick "Writing a Caddy JSON config from scratch" article in our community wiki which should hopefully get you started, at least.

We try to avoid putting lots of examples in the official docs since there are so many possibilities that we can't guess what everyone needs, and we'd rather people read the docs, go through exercises, and understand what they are doing rather than copy-paste examples.

But the wiki is a great place for community-contributed examples if you want to write some there!

What is it about understanding the JSON that you find difficult? Instead of examples, maybe we should start from there.

[phish108]

@mholt thank you for your reply. I can fully understand the time issues.

Thank you for the pointer to the wiki. I will certainly have a closer look.

Regarding the Caddyfile keywords in the docs, I think the JSON representation offers more than examples because a lot of features don't translate intuitively between the formats. E.g., the handle_path or uri keywords have no reasonable match in the JSON config. Instead, the docs are misleading in this case because they state that no rewrite takes place, but in JSON format the rewrite handler is used.

I just found that caddy adapt --validate --config ${MYCONFIG} gives me what I need for handling partial Caddyfiles. I pluck the relevant fragment from the result using jq before forwarding it to the API. This info would be very useful within the API docs.

[mholt]

@phish108

the docs are misleading in this case because they state that no rewrite takes place

Where does it say that? In fact, the uri and handle_path directives are wrappers over the underlying rewrite JSON handler.

But yeah, directives don't necessarily map 1:1 with handlers. So even the rewrite directive is kind of a special kind of rewrite that maps URIs to something else.

I just found that caddy adapt --validate --config ${MYCONFIG} gives me what I need for handling partial Caddyfiles. I pluck the relevant fragment from the result using jq before forwarding it to the API. This info would be very useful within the API docs.

I guess we could do that, but the API is orthogonal to the Caddyfile. We introduce this command in the very first Getting Started guide that all users should be reading anyway. 👍

[phish108]

Thank you. Your comments help me to understand caddy better.

the docs are misleading in this case because they state that no rewrite takes place

Where does it say that? In fact, the uri and handle_path directives are wrappers over the underlying rewrite JSON handler.

The first part was crystal clear to me. But the second part just became evident to me from the config translation but not from the uri documentation. There the second paragraph states that rewrite and uri are/do different things. Maybe I got confused because Caddyfile rewrite appears not to be the same as caddy-JSON rewrite.

But yeah, directives don't necessarily map 1:1 with handlers. So even the rewrite directive is kind of a special kind of rewrite that maps URIs to something else.

Without the corresponding JSON, it was quite difficult for me to understand this mapping. I was even looking for an uri handler but could not find it (obviously).

I just found that caddy adapt --validate --config ${MYCONFIG} gives me what I need for handling partial Caddyfiles. I pluck the relevant fragment from the result using jq before forwarding it to the API. This info would be very useful within the API docs.

I guess we could do that, but the API is orthogonal to the Caddyfile.

👍 I really like the API for pushing new parts of configurations to caddy as they appear in the environment. Getting the configuration of these sections right is just a much easier using the Caddyfile format.

We introduce this command in the very first Getting Started guide that all users should be reading anyway. 👍

I saw the adapt command in the guide but without the --validate option. From the guide I took that adapt and run are the ways to replace a configuration as a whole without using the API, which I do not want.

However, with --validate option this command turns into a Caddyfile to caddy-JSON translator (probably even nginx config to caddy-JSON converter, I guess). I find this a pretty cool feature on its own and that this is possible is not clear in the docs.

The docs on the command also don't state that adapt --validate will translate fragments of Caddyfiles correctly into caddy-JSON, which is also a nice trick to know.

My process is now: Caddyfile -> caddy adapt --validate -> jq extraction -> API injection.

[francislavoie]

--validate doesn't do anything extra at all for adapting the config. It just calls the Provision() and Validate() functions on the configured modules, after adapting the Caddyfile to JSON. It's not required at all. Without it, you still get the final JSON config.

[mholt]

I kind of like the idea of showing the corresponding JSON somehow in the Caddyfile docs. Maybe optionally expandable. (<details> tag or something).

Francis is right though, caddy adapt is all you need to get JSON from a Caddyfile (or other format). --validate just loads the config first, but it has nothing to do with the resulting JSON.

[phish108]

@francislavoie @mholt thank you regarding adapt --validate.