Cutlery/caddy
1
0
Fork 0
mirror of https://github.com/caddyserver/caddy.git synced 2025-07-09 03:04:57 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity

Improve config adapter docs

Matt Holt 2019-11-08 00:06:51 -07:00
parent 3a0fa7b089
commit e2deee749d
1 changed files with 4 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
v2:-Documentation.md

@ -473,13 +473,13 @@ All contexts support the global placeholders:
## Config adapters
Caddy's native config language is JSON, but writing JSON by hand can be tedious and error-prone. That's why Caddy supports being configured with other means through _config adapters_. They make it possible to use config in a more comfortable or convenient format by outputting Caddy JSON for you.
Caddy's native config language is JSON, but writing JSON by hand can be tedious and error-prone. That's why Caddy supports being configured with other means through _config adapters_. They make it possible to use config in a more comfortable or convenient format by outputting Caddy JSON for you. For example, a config adapter may turn your NGINX config into Caddy JSON.
Config adapters do their best to translate your input to Caddy JSON with the highest fidelity and correctness, but some features/behaviors don't translate well or are not yet programmed. Because this conversion process is not guaranteed to be complete and correct all the time, we don't call them "converters" or "translators". They are "adapters" since they will at least give you a good starting point to finish crafting your final JSON config.
Config adapters do their best to translate your input to Caddy JSON with the highest fidelity and correctness, but some features/behaviors don't translate well or are not yet programmed. Because this conversion process is not guaranteed to be complete and correct all the time, we don't call them "converters" or "translators". They are "adapters" since they will at least give you a good starting point to finish crafting your final JSON config. That said, the Caddyfile format is specifically designed for Caddy, so any and all of the Caddyfile's features should translate to Caddy JSON correctly and completely. The Caddyfile adapter is a special case in this sense.
That said, the Caddyfile format is specifically designed for Caddy, so any and all of the Caddyfile's features should translate to Caddy JSON correctly and completely. The Caddyfile adapter is a special case in this sense.
Config adapters can output the resulting JSON, warnings, and errors. JSON results if no errors occur. Errors occur when something is wrong with the input (for example, syntax errors). Warnings are emitted when something is wrong with the adaptation but which is not necessarily fatal (for example, feature not supported). Caution is advised if using configs adapted with warnings.
Generally, config adapters will output warnings when something cannot be adapted in a way that would be expected. if the behavior cannot be replicated perfectly in Caddy, or if the feature doesn't make sense in Caddy, or if the adapter simply doesn't cover all the possible use cases yet. However, warnings are not errors, and for this reason we advise against simply throwing your NGINX config into the NGINX config adapter using `caddy run` to immediately start your server without first verifying the adapter's output. You can use the [`adapt`](#adapt) command for this.
You can use config adapters simply by specifying the `--config` and `--adapter` flags with the [`caddy adapt`](#adapt), [`caddy start`](#start), and [`caddy run`](#run) commands.
Config adapters are an exciting and unique feature. We hope you will help contribute to the config adapters!