Caddy: Rewrites and Redirects

Welcome back! Let's take a look at two powerful Caddy features: Rewrites and Redirects

What is a URI?

The URI is the part of a link that comes after the fully-qualified domain name. For example:

www.skip2.net**/assets/squirrel.jpg**

/assets/squirrel.jpg

The URI is the part in bold. URI stands for Uniform Resource Identifier and is one way that you interact with websites.

Rewrites

With Caddy, you can easily rewrite and manipulate URIs to fit your application. Let's look at the example below:

my-site.com {
	reverse_proxy localhost:8080
}

api.my-site.com {
	reverse_proxy 10.0.0.5:8080
}

We have two sites, our main application site at my-site.com and our API at api.my-site.com. We proxy requests for these two domains to different servers, one running locally and another at 10.0.0.5. But, wait a minute, our API server expects all request URIs to be prefixed with "/api/" - a full request URL would look like "api.my-site.com/api/account/config" - how redundant! Let's give our customers a break and use a Caddy rewrite to fix this.

Since our API expects to receive requests at e.g. "10.0.0.5:8080/api/account/config" but we want people to be able to send them to our Caddy server as "api.my-site.com/account/config" - add one line and it's done:

my-site.com {
	reverse_proxy localhost:8080
}

api.my-site.com {
	rewrite * /api{uri}
	reverse_proxy 10.0.0.5:8080
}

This one-liner is doing a lot, so let's break it down. rewrite is the directive to tell Caddy to rewrite requests matching the matcher we provided - in this case, an *. The asterisk matches all requests, so for all requests we will rewrite the URI with "/api{uri}" - prefixing the requests with our /api. {uri} is a Caddy placeholder that prints the request's original URI. If a requests comes in as "api.my-site.com/account/config" it will be rewritten as "api.my-site.com/api/account/config" and proxied to our API server.

Redirects

Redirects are fairly simple and built-in to HTTP. Caddy keeps rediect configuration simple. Let's look at our example again.

my-site.com {
	redir https://www.my-site.com{uri} permanent
	reverse_proxy localhost:8080
}

api.my-site.com {
	redir https://my-site.com/maintenance html
	#rewrite * /api{uri}
	#reverse_proxy 10.0.0.5:8080
}

blog.my-site.com {
	redir https://my-site.com/maintenance temporary
}

*rest of the sites...*

In this last example, we redirect three sites differently. First, for my-site.com, we put in an permanent (HTTP 301) redirect to www.my-site.com (www.my-site.com configuration not relevant/shown). Second, we've taken our API down for maintenance. We want to redirect any browser users to our maintenance page but we don't want to redirect API clients to prevent errors. The "HTML" redirect is perfect for this, generating an HTML document to serve to a browser and perform the redirect. Lastly, we're migrating the blog to a new location so it's down for maintenance too, and we're redirecting it to our maintenance page temporarily, with an HTTP 302 (which is default if no redirect type is specified).

Continue Reading

Learn more about using Caddy web server and the Rewrite and Redirect features on Caddy's official documentation site: Rewrites and Redirects

Wrapping up

Caddy makes these two essential web server functions easy to configure and quick to deploy.

Want to learn more about Caddy?

Visit their official website at caddyserver.com Read through the docs at caddyserver.com/docs If you use it, sponsor the project (we do!) caddyserver.com/sponsor

This post is one of a series of tutorials about Caddy Server. You can view all relevant posts here.

Learn about Skip2

Get Started