HTTPS in Development

Local development environments typically run over http (ie: http://localhost) out of the box. This guide will discuss when you should run a local server over https and how to configure https on localhost.

When to use a local https server

Web browsers behave differently on http vs https, to account for these differences you may require your dev server to serve pages over https. For example:

  • When your page is served over https, requests to load resources from an http URL will be blocked. You may want this behavior locally to avoid bugs that would only trigger in the production environment or because you don’t want to make http requests containing sensitive information in error.

  • Cookies using a Secure attribute or SameSite attribute set to None will not be sent across insecure channels, disrupting authentication and other functionality.

How to set up a secure local server

The idea is to run a web server in front of your local development server that will accept https requests and forward them to your application's web server over http, thus serving your application's requests over https by proxy. This is called an https reverse proxy and we can use an off the shelf product called Caddy to create an https reverse proxy.

The process to do this is:

  1. Download the Caddy binary

  2. Run your application's web server over http as normal

  3. Run the Caddy binary as a reverse proxy telling it to forward traffic to your application's web server

  4. Visit the reverse proxy web server over https

1. Download the Caddy binary

Visit https://caddyserver.com/download, select your platform and download the file to your computer.

2. Run your application's web server over http as normal

Run your application’s local development server as normal, for example $ PORT=3000 npm start

3. Run the Caddy binary as a reverse proxy telling it to forward traffic to your application's web server

Find the location of your downloaded Caddy binary and run the following command to create a reverse proxy and forward requests from port 443 (the default port used for https) to your application's port (in this case 3000): 

/path/to/caddy reverse-proxy --from localhost:443 --to localhost:3000

Was this helpful?

/

4. Now visit your web server over https

Visit https://localhost and it will serve your application's requests over https

Running your application behind a proxy

You may have to make some slight adjustments to you application when it is running behind a proxy.

For example in Express.js, although the app will not fail to run, it will incorrectly register the proxy’s IP address as the client IP address unless trust proxy is configured, see https://expressjs.com/en/guide/behind-proxies.html