HTTPS and subdomains on localhost with Caddy Server

I was working on a multi-tenant application that required tenants to log in on their own subdomain. The subdomain would be used to identify the tenant for Firebase multi-tenancy authentication and MongoDB documents. I knew it was simple to set up subdomain support in production using something like Vercel wildcard domains, but I didn't know how to handle this in development.

Around the same time, I listened to a Syntax.fm podcast called Servers with Matt from Caddy. In this podcast, they discussed how Caddy simplified web servers, including how easy it is to set up HTTPS and subdomains. I never used Caddy, but after using it I was amazed at how quickly I was able to get HTTPS and a subdomain setup on localhost.

Watch the lesson

Install Caddy Server

You have several options for installing Caddy Server on your computer, which is outlined in the Caddy Getting Started documentation.

I do the majority of my development on a Mac and already used Homebrew as a package manager, so I opted for the community-maintained Homebrew option. On a Windows machine, I use Chocolatey as a package manager, so I would opt for the community-maintained Chocolatey option.

Regardless of what option you choose, all you need to do is to follow the simple installation instructions outlined in the Caddy documentation.

Caddyfile

In order to run a web server with Caddy, you can use the API or a Caddyfile. I like to use a Caddyfile because it lives at the root of my projects and accessible to anyone that gets the code from GitHub.

To set up a subdomain with HTTPS you need to create a text file named Caddyfile (no extension) at the root of your project and add the following code:

subdomain.localhost {
    reverse_proxy localhost:3000
}

This simple configuration code will tell Caddy to create a subdomain that you can access in your browser at subdomain.localhost for an application running on localhost:3000. Be sure to change subdomain and port 3000 based on your application. Also, this is a simple configuration example–be sure to check out the Caddyfile documentation for all the options.

The next thing you'll need to do is run your local server. This will depend on your project, but the example from the video is a Next.js project, so I can run npm run dev in my VS Code terminal to get my development server running.

Once your development server is running you can open a new terminal tab within your project and run the command caddy run. This will look for the Caddyfile in your project and use the configuration to start the webserver. You can now visit subdomain.localhost in your browser with a secure SSL (HTTPS) connection!

Conclusion

Your standard localhost development environment might be sufficient for most projects, but when you need features like SSL and subdomain support you can turn to Caddy to make your life easier.

We only touched briefly on everything Caddy can do, so be sure to visit Caddy Server to see what else it can help you with for your applications.