Migrate FAQ from readme

v2:-FAQ.md

@@ -0,0 +1,146 @@
+### How do I configure Caddy 2?
+
+Caddy's primary mode of configuration is a REST API, which accepts a JSON document. The JSON structure is described [interactively in the docs](https://caddyserver.com/docs/json/). 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.
+
+Basically, you will [start Caddy](https://caddyserver.com/docs/command-line#caddy-run), then [POST a JSON config to its API endpoint](https://caddyserver.com/docs/api#post-load).
+
+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://caddyserver.com/docs/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.
+
+### Caddy 2 feels harder to use. How is this an improvement over Caddy 1?
+
+Caddy's ease of use is one of the main reasons it is special. We are not taking that away in Caddy 2, but first we had to be sure to tackle the fundamental design limitations with Caddy 1. Usability can then be layered on top. This approach has several advantages which we discuss in the next question.
+
+### What about the Caddyfile; are there easier ways to configure Caddy 2?
+
+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).
+
+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.
+
+Caddy's default _config adapter_ is the Caddyfile adapter. This takes a Caddyfile as input and [outputs the JSON config](https://caddyserver.com/docs/command-line#caddy-adapt). You can even run Caddy directly without having to see or think about the underlying JSON config.
+
+The following _config adapters_ are already being built or plan to be built:
+
+- Caddyfile
+- JSON 5
+- JSON-C
+- nginx
+- YAML
+- TOML
+- any others that the community would like to contribute
+
+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.
+
+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.
+
+However, we expect that most users will be able to use the Caddyfile (or another easy config adapter) exclusively for their sites.
+
+### Why JSON for configuration? Why not _<any other serialization format>_?
+
+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.
+
+JSON may not be the fastest, the most compact, the easiest to write, serialization format that exists. But those aren't our goals. It has withstood the test of time and checks all our boxes.
+
+- It is almost entirely ubiquitous. JSON works natively in web browsers and has mature libraries in pretty much every language.
+- It is human-readable (as opposed to a binary format).
+- It is easy to tweak by hand. Although composing raw JSON by hand is not awesome, this will not be mainstream once our config adapters are done.
+- It is generally easy to convert other serializations or config formats into JSON, as opposed to the other way around.
+- Even though JSON deserialization is not fast per-se, that kind of performance is not really a concern since config reloads are not the server's hottest path like HTTP request handling or TLS handshakes are. Even with JSON, Caddy 2 can handle dozens of config changes per second, which is probably plenty for now.
+- It maps almost 1:1 to the actual, in-memory values that power your HTTP handlers and other parts of the server (no need to parse a config file with some arbitrary DSL and do a bunch of extra pre-processing).
+
+Ultimately, we think all these properties are appropriate -- if not ideal -- for a web server configuration.
+
+If you're still not happy with the choice of JSON, feel free to contribute a config adapter of your own choice!
+
+Or just use YAML or TOML, which seamlessly translate to JSON.
+
+### JSON is declarative; what if I need more programmability (i.e. imperative syntax)?
+
+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/).
+
+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.
+
+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.
+
+However, sometimes computation is useful, and in some cases, the only way to express what you need. This can be illustrated really well in the simple case of trying to decide whether a particular HTTP middleware should be invoked as part of an HTTP request. A lot of the time, such logic is as simple as: "GET requests for any path starting with /foo/bar", which can be expressed declaratively in JSON:
+
+```json
+{
+	"method": "GET",
+	"path": "/foo/bar"
+}
+```
+
+But what if you need to match /foo/bar OR /topaz? How do you express that OR clause? Maybe an array:
+
+```json
+{
+	"method": ["GET"],
+	"path": ["/foo/bar", "/topaz"]
+}
+```
+
+Now what if you need add a NOT or AND clause? JSON quickly tires out. As you learn about Caddy 2's request matching, you will see how we handled this. Caddy 2's JSON gives you the ability to express moderately-complex logic such as:
+
+```js
+// this is not actual Caddy config, just logic pseudocode
+IF (Host = "example.com")
+	OR (Host = "sub.example.com" AND Path != "/foo/bar")
+```
+
+Already, this is more expressive power than most web servers offer with their native config, yet Caddy 2 offers this in JSON.
+
+But in most web servers, to make logic this complex feasible, you'll generally call out to Lua or some extra DSL. For example, in NGINX you could use a Lua module to express this logic. Traefik 2.0 has [yet another kind of clunky-looking custom DSL](https://blog.containo.us/back-to-traefik-2-0-2f9aa17be305#d22e) just for this.
+
+Caddy 2 solves this in a novel way with [Starlark expressions](https://godoc.org/go.starlark.net/starlark#Eval). Starlark is a familiar dialect of Python! So, no new DSLs to learn and no VMs to slow things down:
+
+```python
+req.host == 'example.com' ||
+	(req.host == 'sub.example.com' && req.path != '/foo/bar')
+```
+
+Starlark performs at least as well as NGINX+Lua (more performance tests ongoing, as well as optimizations to make it even faster!) and because it's basically Python, it's familiar and easy to use.
+
+In summary: Caddy 2 config is declarative, but can be imperative where that is useful.
+
+### What is Caddy 2 licensed as?
+
+Caddy 2 is licensed under the Apache 2.0 open source license. There are no official Caddy 2 distributions that are proprietary.
+
+### Does Caddy 2 have telemetry?
+
+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.
+
+## Does Caddy 2 use HTTPS by default?
+
+Yes. HTTPS is automatic and enabled by default when possible, just like in Caddy 1. Basically, if your HTTP routes specify a `host` matcher with qualifying domain names, those names will be enabled for automatic HTTPS. Automatic HTTPS is disabled for domains which match certificates that are manually loaded by your config.
+
+## How do I avoid Let's Encrypt rate limits with Caddy 2?
+
+As you are testing and developing with Caddy 2, you should use test ("staging") certificates from Let's Encrypt to avoid rate limits. By default, Caddy 2 uses Let's Encrypt's production endpoint to get real certificates for your domains, but their [rate limits](https://letsencrypt.org/docs/rate-limits/) forbid testing and development use of this endpoint for good reasons. You can switch to their [staging endpoint](https://letsencrypt.org/docs/staging-environment/) by adding the staging CA to your automation policy in the `tls` app:
+
+```json
+"tls": {
+	"automation": {
+		"policies": [
+			{
+				"management": {
+					"module": "acme",
+					"ca": "https://acme-staging-v02.api.letsencrypt.org/directory"
+				}
+			}
+		]
+	}
+}
+```
+
+Or with the Caddyfile, using a global options block at the top:
+
+```
+{
+	acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
+}
+```
+
+## Can we get some access controls on the admin endpoint?
+
+Yeah, that's coming. For now, you can use a permissioned unix socket for some basic security.