From 82b700290144c84d20cb9223f7d30bf354f5aae5 Mon Sep 17 00:00:00 2001 From: Matthew Holt Date: Mon, 15 Aug 2022 18:12:34 -0600 Subject: [PATCH] tutorials: Enhance reverse proxy quick-start --- .../markdown/quick-starts/reverse-proxy.md | 89 +++++++++++++++---- .../markdown/quick-starts/static-files.md | 2 +- 2 files changed, 71 insertions(+), 20 deletions(-) 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