docs: New "Introduction" tutorial

[mholt]

Our current Getting Started tutorial (as of early September 2022) is a classic guide on our Caddy 2 site. It is required reading, as it demonstrates the basic caddy commands, how to load configuration both as native JSON and config adapters, and helps you choose how to run and configure Caddy. It sets a crucial foundation, then lets you choose how to take it from there.

I really like that guide and it needs to stay (in some form or another). But we get a lot of feedback that it's not very practical. It doesn't help them actually "get started" with the web server. There's too many directions to take it once you know how to load config and such. But I think that's OK. You just gotta write your config and then apply what you learned in Getting Started. It, along with our other quick-starts and tutorials, are excellent universal guides for using Caddy, IMO.

In this PR, I've added a new "Introduction" tutorial to be more practical, inspired by https://ellen.dev/serve-static-site-using-caddy.html. It's probably more comprehensive for beginners. Unfortunately, it steps outside the scope of Caddy and goes into sysadmin territory, which I don't like doing, because it's not our job to document Linux or systemd.

Another problem is that this revision in its current form is Linux-only. That is the vast majority of users by far, but it doesn't represent everyone, especially many who are just trying it "at home" (Windows and Mac). This tutorial should be universal, and I don't want to maintain 3 versions of it, or multiple versions of sub-sections, for various OSes, frankly. I still think it is reasonable to expect that readers know how to use their computers already. To learn how to use the computer is outside the scope of our documentation and is a better fit for our wiki.

Additionally, this tutorial is harder. There's more to read, it moves more slowly, and it feels more complex. The problem is that this reflects poorly on Caddy even though the slowness and complexity is entirely due to how Linux and systemd work.

Lots of people are suggesting using Docker for this universal tutorial, but I have a hard reservation against that, as Docker is often the cause of many complications and confusion in our experience. I think Docker would be fine for an advanced tutorial, but I maintain that the point of our docs is to teach Caddy, not sysadmin.

There is currently not a great transition from Introduction to Getting Started.

Still a WIP.

---

If you're new here and want to read this locally, it's easy:

$ git clone https://github.com/caddyserver/website.git
$ cd website
$ git checkout origin/introduction
$ caddy run

then open https://localhost

[Plorenzo]

I've been following Caddy and you for a long time now so I think I have a pretty good sense of how reluctant you are to teach Caddy users how to use computers so first of all thanks for giving this a try!

While in theory and in the ideal world, I agree with you, system administration is outside the scope of Caddy, in practice most users (me a few years ago included, you can see me struggle in the forum 😂) want a default, recommended by the vendor way of deploying the software, as it makes the onboarding experience much smoother. Downloading a binary and not knowing what to do with it can be overwhelming for newbies. Advances users already know they have many different ways of doing it to fit their needs best and are less likely to just follow the official docs.

So the review from me is that this looks very good, is concise, clear, very easy to follow and clearly highlights the few nuances that you should be aware of. Thumbs up 👍👍

I would like to add just a few nitpicks for your consideration.

1. I wouldn't call it introduction
   Even with this tutorial in the docs, I think you should still read Getting started first and naming it introduction makes it look like it's the first required read. So I would rename it to something like Serving your first site tutorial or Simple Caddy production set up or similar.

2. Add mention to caddy fmt and validate.
   On section Your first site after reloading the config with sudo systemctl reload caddy you mention what to do if the command fails, I think it will be great to mention that you can run caddy fmt --overwrite /etc/caddy/Caddyfile and caddy validate --config /etc/caddy/Caddyfile before triggering the reload to minimise silly mistakes.

3. Add quick mention to caddy-dynamicdns
   On section HTTPS you say:

Before continuing, point your domain to your server's IP address. This means setting the value of your domain's A/AAAA record(s) to the public IP address of your server.

I would add quick note saying that caddy can do that for you using caddy-dynamicdns, not explaining how it's done, as it would add a bit of unnecessary noise to the tutorial but a quick mentions would help with discoverability of that very very handy plugin.

4. Lastly, a very tiny one. Write at least once the full form of CA (certificate authority)
   On section Certificates there are several mentions to CA, which maybe everyone should know what it means, but probably that's not the case and a quick googling of "CA" is not very helpful.

[francislavoie]

I think this would need a mention about directive sorting, otherwise it's not obvious why this would work (they might try using a matcher and assume it'll "just work" but it might not depending on the combination of directives).

[francislavoie]

I think this is misleading, because most of the time, this won't work.

For PHP apps, you need to configure root to your app's webroot, which should almost never be the actual root of the project, but actually a public/ dir inside of the project. This is important for security so that random PHP scripts as part of the actual app can't be directly executed, or metadata/secret files (like a .env) can't be served by the file server.

And if you use a path matcher, it doesn't change the try_files logic within the directive, so it will still look for index.php at the configured root, and not inside of some /api directory within the project.

[mholt]

Just FYI I'm considering this feedback for our new Caddy website which I'm working on.