diff --git a/src/docs/markdown/quick-starts/reverse-proxy.md b/src/docs/markdown/quick-starts/reverse-proxy.md index 965a22f..f420c0e 100644 --- a/src/docs/markdown/quick-starts/reverse-proxy.md +++ b/src/docs/markdown/quick-starts/reverse-proxy.md @@ -4,7 +4,7 @@ title: Reverse proxy quick-start # Reverse proxy quick-start -This guide will show you how to get a production-ready reverse proxy up and running quickly. +This guide will show you how to get a production-ready reverse proxy with or without HTTPS up and running quickly. **Prerequisites:** - Basic terminal / command line skills @@ -13,51 +13,102 @@ This guide will show you how to get a production-ready reverse proxy up and runn --- -There are two easy ways to get a quick reverse proxy up and running. We'll show you two equivalent ways to do the same thing. +This tutorial assumes that you have a backend HTTP service running at `127.0.0.1:9000`. These commands are for Linux, but the same principles apply to other operating systems. -This tutorial assumes you have a backend HTTP service running on `127.0.0.1:9000`. +You can get a simple reverse proxy running without a config file, or you can use a config file for more flexibility and control. ## Command line -In your terminal, run this command: +To start a plaintext HTTP proxy from port 2080 to port 9000 on your machine: -
caddy reverse-proxy --to 127.0.0.1:9000
+caddy reverse-proxy --from :2080 --to :9000
-If you don't have permission to bind to low ports, you can proxy from a higher port:
-
-caddy reverse-proxy --from :2016 --to 127.0.0.1:9000
-
-Then make a request to [localhost](https://localhost) (or whatever address you specified in `--from`) to see it working!
+Then try it:
+curl -v 127.0.0.1:2080
+The [`reverse-proxy` command](/docs/command-line#reverse-proxy) is intended for quick and easy reverse proxies. (You can use it in production if your requirements are simple.)
## Caddyfile
In the current working directory, create a file called `Caddyfile` with these contents:
```caddy
-localhost
+:2080
-reverse_proxy 127.0.0.1:9000
+reverse_proxy :9000
```
+That config file is roughly equivalent to the `caddy reverse-proxy` command above.
+
Then, from the same directory, run:
caddy run
-You can then make a request to [https://localhost](https://localhost) to see it working!
+Then try your proxy:
-It's easy to change the proxy's address:
+curl -v 127.0.0.1:2080
+
+If you change the Caddyfile, make sure to [reload](/docs/command-line#caddy-reload) Caddy.
+
+This was a simple example. You can do a lot more with the [`reverse_proxy` directive](/docs/caddyfile/directives/reverse_proxy).
+
+## HTTPS from client to proxy
+
+Caddy will serve your proxy over [HTTPS automatically and by default](/docs/automatic-https) if it knows the hostname (domain name). The `caddy reverse-proxy` command will default to `localhost` if you omit the `--from` flag, or you can replace the first line of your Caddyfile with the domain name of the proxy.
+
+- If you use `localhost` or any domain ending in `.localhost`, Caddy will use an auto-renewing self-signed certificate. The first time you do this, you may need to enter a password as Caddy attempts to install its CA's root certificate into your trust store.
+- If you use any other domain name, Caddy will attempt to get a publicly-trusted certificate; make sure your DNS records point to your machine and that ports 80 and 443 are open to the public and directed toward Caddy.
+
+If you don't specify a port, Caddy defaults to 443 for HTTPS. In that case you will also need permission to bind to low ports. A couple ways to do this on Linux:
+
+- Run as root (e.g. `sudo -E`).
+- Or run `sudo setcap cap_net_bind_service=+ep $(which caddy)` to give Caddy this specific capability.
+
+Here's the most basic `caddy reverse-proxy` command that gives you HTTPS:
+
+caddy reverse-proxy --to :9000
+
+Then try it:
+
+curl -v https://localhost
+
+You can customize the hostname using the `--from` flag:
+
+caddy reverse-proxy --from example.com --to :9000
+
+If you don't have permission to bind to low ports, you can proxy from a higher port:
+
+caddy reverse-proxy --from example.com:8443 --to :9000
+
+If you're using a Caddyfile, simply change the first line to your domain name, for example:
```caddy
-:2016
+example.com
-reverse_proxy 127.0.0.1:9000
+reverse_proxy :9000
```
-Make sure to [reload](/docs/command-line#caddy-reload) Caddy (or stop and start it again) when you change the Caddyfile.
+## HTTPS from proxy to backend
-Now you can access the proxy at [localhost:2016](http://localhost:2016).
+Caddy can also proxy using HTTPS between itself and the backend if the backend supports TLS. Just use `https://` in your backend address:
-There is a lot more you can do with the [`reverse_proxy` directive](/docs/caddyfile/directives/reverse_proxy).
\ No newline at end of file
+caddy reverse-proxy --from :2080 --to https://localhost:9000
+
+This requires that the backend's certificate is trusted by the system Caddy is running on. (Caddy doesn't trust self-signed certificates unless explicitly configured to do so.)
+
+Of course, you can do HTTPS on both ends too:
+
+caddy reverse-proxy --from example.com --to https://localhost:9000
+
+This serves HTTPS from client to proxy, and from proxy to backend.
+
+If the hostname you're proxying to is different than the one you're proxying from, you will need to use the `--change-host-header` flag:
+
+caddy reverse-proxy \
+ --from example.com \
+ --to https://localhost:9000 \
+ --change-host-header
+
+By default, Caddy passes all HTTP headers through unchanged, including `Host`, and Caddy derives the TLS ServerName from the Host header. The `--change-host-header` resets the Host header to that of the backend so that the TLS handshake can complete successfully. In the example above, it would be changed from `example.com` to `localhost:9000` (and `localhost` would be used in the TLS handshake).
diff --git a/src/docs/markdown/quick-starts/static-files.md b/src/docs/markdown/quick-starts/static-files.md
index e977902..ed4e1be 100644
--- a/src/docs/markdown/quick-starts/static-files.md
+++ b/src/docs/markdown/quick-starts/static-files.md
@@ -13,7 +13,7 @@ This guide will show you how to get a production-ready static file server up and
---
-There are two easy ways to get a quick file server up and running. We'll show you two equivalent ways to do the same thing.
+There are two easy ways to get a quick file server up and running.
## Command line