59910923 · marcel91200/caddy · siGit Code & Deploy

@@ -109,6 +109,43 @@ Note that this will stop any process named the same as `os.Args[0]`.

109

110 For other commands, please see [the Caddy 2 documentation](https://github.com/caddyserver/caddy/wiki/v2:-Documentation).

111

112 +### Caddyfile

113 +

114 +Caddy 2 can be configured with a Caddyfile, much like in v1, for example:

115 +

116 +```plain

117 +example.com

118 +

119 +templates

120 +encode gzip zstd

121 +try_files {path}.html {path}

122 +proxy /api http://localhost:9005

123 +file_server

124 +```

125 +

126 +Instead of being its core method of configuration, an internal _config adapter_ adapts the Caddyfile to Caddy's native JSON structure. You can see it in action with the [`adapt-config` command](https://github.com/caddyserver/caddy/wiki/v2:-Documentation#adapt-config):

127 +

128 +```bash

129 +$ ./caddy adapt-config --input path/to/Caddyfile --adapter caddyfile --pretty

130 +```

131 +

132 +But if you just want to run Caddy with your Caddyfile directly, the CLI wraps this up for you nicely. Either of the following commands:

133 +

134 +```bash

135 +$ ./caddy start

136 +$ ./caddy run

137 +```

138 +

139 +will apply your Caddyfile if it is called `Caddyfile` in the current directory.

140 +

141 +If your Caddyfile is somewhere else, you can still use it:

142 +

143 +```bash

144 +$ ./caddy start|run --config path/to/Caddyfile --config-adapter caddyfile

145 +```

146 +

147 +[Learn more about the Caddyfile in v2.](https://github.com/caddyserver/caddy/wiki/v2:-Documentation#caddyfile-adapter)

148 +

149

150 ## Configuration

151

@@ -118,7 +155,7 @@ Nearly all of Caddy 2's configuration is contained in a single config document,

155

156 To wield the power of this design, you need to know how the config document is structured. Please see the [the Caddy 2 documentation in our wiki](https://github.com/caddyserver/caddy/wiki/v2:-Documentation) for details about Caddy's config structure.

157

121 -Configuration is normally given to Caddy through an API endpoint, which is likewise documented in the wiki pages.

158 +Configuration is normally given to Caddy through an API endpoint, which is likewise documented in the wiki pages. However, you can also use config files of various formats with [config adapters](https://github.com/caddyserver/caddy/wiki/v2:-Documentation#config-adapters).

159

160

161 ## Full Documentation

@@ -192,9 +229,11 @@ And a few major features still being worked on:

229

230 ### How do I configure Caddy 2?

231

195 -First you need to build a configuration document, which is in JSON. You may wish to write in YAML or TOML and then convert to JSON, that is fine too. The structure is described [in the wiki](https://github.com/caddyserver/caddy/wiki/v2:-Documentation).

232 +Caddy's primary mode of configuration is a REST API, which accepts a JSON document. The JSON structure is described [in the wiki](https://github.com/caddyserver/caddy/wiki/v2:-Documentation). The advantages of exposing this low-level structure are 1) it has near-parity with actual memory initialization, 2) it allows us to offer wrappers over this configuration to any degree of convenience that is needed, and 3) it performs very well under rapid config changes.

233 +

234 +Basically, you will [start Caddy](https://github.com/caddyserver/caddy/wiki/v2:-Documentation#start), then [POST a JSON config to its API endpoint](https://github.com/caddyserver/caddy/wiki/v2:-Documentation#post-load).

235

197 -Once you have your configuration document ready, you need to give it to Caddy. This can be done at startup or while it's running. See the instructions above for how to do this.

236 +Although this makes Caddy 2 highly programmable, not everyone will want to configure Caddy via JSON with an API. Sometimes we just want to give Caddy a simple, static config file and have it do its thing. That's what **[config adapters](https://github.com/caddyserver/caddy/wiki/v2:-Documentation#config-adapters)** are for! You can configure Caddy more ways than one, depending on your needs and preferences. See the next questions that explain this more.

237

238 ### Caddy 2 feels harder to use. How is this an improvement over Caddy 1?

239

@@ -202,7 +241,11 @@ Caddy's ease of use is one of the main reasons it is special. We are not taking

241

242 ### What about the Caddyfile; are there easier ways to configure Caddy 2?

243

205 -Yes; or there will be, soon. Caddy's native configuration language is JSON (see next question), but the advantage of exposing this low-level structure that has near-parity with actual memory initialization allows us to offer wrappers over this configuration to any degree of flexibility that is needed without suffering a significant performance hit during reloads.

244 +Yes! Caddy's native JSON configuration via API is nice when you are automating config changes at scale, but if you just have a simple, static configuration in a file, you can do that too with the [Caddyfile](https://github.com/caddyserver/caddy/wiki/v2:-Documentation#caddyfile-adapter).

245 +

246 +The v2 Caddyfile is very similar to the v1 Caddyfile, but they are not compatible. Several improvements have been made to request matching and directives in v2, giving you more power with less complexity and fewer inconsistencies.

247 +

248 +Caddy's default _config adapter_ is the Caddyfile adapter. This takes a Caddyfile as input and [outputs the JSON config](https://github.com/caddyserver/caddy/wiki/v2:-Documentation#adapt-config). You can even run Caddy directly without having to see or think about the underlying JSON config.

249

250 The following _config adapters_ are already being built or plan to be built:

251

@@ -212,14 +255,12 @@ The following _config adapters_ are already being built or plan to be built:

255 - TOML

256 - any others that the community would like to contribute

257

215 -When finished, config adapters will allow you to configure Caddy not just one way but _any_ of these ways. For example, you'll be able to bring your existing NGINX config to Caddy and it will spit out the Caddy config JSON you need (to the best of its ability). How cool is that! You can then easily tweak the resulting config by hand, if necessary.

258 +Config adapters allow you to configure Caddy not just one way but _any_ of these ways. For example, you'll be able to bring your existing NGINX config to Caddy and it will spit out the Caddy config JSON you need (to the best of its ability). How cool is that! You can then easily tweak the resulting config by hand, if necessary.

259

260 All config adapters vary in their theoretical expressiveness; that is, if you need more advanced configuration you'll have to drop down to the JSON config, because the Caddyfile or an nginx config may not be expressive enough.

261

262 However, we expect that most users will be able to use the Caddyfile (or another easy config adapter) exclusively for their sites.

263

221 -(The Caddyfile will be upgraded from version 1 to support common use cases that are a bit painful with the current v1 Caddyfile.)

222 -

264 ### Why JSON for configuration? Why not _<any other serialization format>_?

265

266 We know there might be strong opinions on this one. Regardless, for Caddy 2, we've decided to go with JSON. If that proves to be a fatal mistake, then Caddy 3 probably won't use JSON.

@@ -241,7 +282,9 @@ Or just use YAML or TOML, which seamlessly translate to JSON.

282

283 ### JSON is declarative; what if I need more programmability (i.e. imperative syntax)?

284

244 -We have good news.

285 +NGINX also realized the need for imperative logic in declarative configs, so they tried "if" statements, [but it was a bad idea](https://www.nginx.com/resources/wiki/start/topics/depth/ifisevil/).

286 +

287 +We have good news. Caddy 2 can give you the power of imperative logic without the perils of mixing declarative and imperative config such as befell NGINX. We do this by allowing embedded imperative syntax awithin the Caddy's declarative config.

288

289 Caddy 2's configuration is declarative because configuration is very much declarative in nature. Configuration is a tricky medium, as it is read and written by both computers and humans. Computers use it, but humans constantly refer to it and update it. Declarative syntaxes are fairly straightforward to make sense of, whereas it is difficult to reason about imperative logic.

290

@@ -292,7 +335,9 @@ Caddy 2 is licensed under the Apache 2.0 open source license. There are no offic

335

336 ### What is Caddy Enterprise?

337

295 -Caddy Enterprise is our web server for businesses that need more advanced features for higher scalability and easier management of clusters. It is built on the same core as Caddy 2, but licensed exclusively to enterprise customers who need it. It includes:

338 +Caddy Enterprise is a collection of plugins for Caddy 2 which provide features and performance that are crucial in business settings. Caddy Enterprise is not a separate web server and does not even use a separate code base from Caddy 2; it is not even a separate branch that merges the open source core in every once in a while. In other words, open source users aren't missing out on a "better" web server, but Enterprise provides features that are used by businesses.

339 +

340 +Caddy Enterprise is for businesses that need more advanced features for higher scalability and easier management of clusters. It includes:

341

342 - a web UI

343 - performance improvements within a cluster

@@ -302,11 +347,13 @@ Caddy Enterprise is our web server for businesses that need more advanced featur

347 - advanced HTTP handlers for authentication, metrics, debugging, and more

348 - dynamic HTTP handlers and TLS handshakes with Starlark

349

305 -Caddy 2 and Caddy Enterprise offer equal levels of security.

350 +Caddy Enterprise can be customized for each customer according to their needs.

351 +

352 +Caddy 2 and Caddy Enterprise offer equal levels of security and, as mentioned, share the same open source code base.

353

354 ### Does Caddy 2 have telemetry?

355

309 -No. There was not enough academic interest to continue supporting it. If telemetry does get added later, it will not be on by default or will be vastly reduced in its scope so that it simply helps the community gain an understanding of how widely Caddy is deployed (i.e. counts of servers running, number of requests/connections handled, etc, but no actual content; just counts).

356 +No. There was not enough academic interest to continue supporting it. If telemetry does get added later, it will not be on by default or will be vastly reduced in its scope so that it simply helps the community gain an understanding of how widely Caddy is deployed (i.e. counts of servers running, number of requests/connections handled, etc).

357

358 ## Does Caddy 2 use HTTPS by default?

359

Update readme for v2 caddyfile and config adapters