Local HTTPS

Gatsby provides a way to use a local HTTPS server during development, thanks to devcert. When you enable the https option, a private key and certificate file will be created for your project and used by the development server.

Usage (automatic HTTPS)

Start the development server using npm run develop as usual, and add either the -S or --https flag.

Setup

When setting up a development SSL certificate for the first time, you may be asked to type in your password after starting the development environment:

On Windows, the prompt will differ:

The password is only required the first time you are using Gatsby’s HTTPS feature on your machine, or when you are creating a brand-new certificate.

Using Certutil

After typing in your password, devcert will install the CA certificate in your operating system trusted certs store. A utility called certutil will be needed to update the trust store for various browsers; specifically: Firefox, and Chrome (when it’s running on Linux).

devcert is configured to install certutil automatically, unless you’re running Windows. If an automatic install is not successful, you may need to install it manually.

Manual installation of Certutil

To install certutil, you need to install the nss tools package(s). The exact procedure will differ depending on your operating system.

Linux

On a Linux OS, you should be able to run one of the following, depending on your Linux distro:

macOS

Run the following command:

Windows

Pre-compiled libraries are rare, so you may need to compile it yourself. Because of how difficult Windows makes it, devcert will not attempt to update the Firefox trust store automatically; instead, it will fall back to using the “Firefox wizard”, detailed below.

Debugging installation

If you choose not to install certutil, or the automatic install is not successful, you may get the following errors/prompts:

Chrome on Linux

Firefox

If you have Firefox installed, devcert will try to utilize Firefox itself to trust the certificate

Your options are as follows:

  • Press enter and it will launch Firefox for you.

  • If you wish to have trust support on Firefox, tell the point-and-click wizard this certificate can identify websites, and click OK. Otherwise, you may hit cancel and close the browser, then key return to finish building. Reminder: you’ll only need to do this once per machine.

After devcert setup process

You can open the development server at https://localhost:8000 and enjoy the HTTPS goodness ✨. You may change the port according to your setup.

Find out more about how devcert works.

Management of certificates generated by devcert

If you want to do some maintenance/cleanup of the certificates generated by devcert, please refer to the devcert-cli

Custom key and certificate files

You may find that you need a custom key and certificate file for HTTPS if you use multiple machines for development (or if your dev environment is containerized in Docker).

If you need to use a custom HTTPS setup, you can pass the --https, --key-file, --cert-file, and --ca-file flags to npm run develop.

  • --cert-file [relative/absolute path to SSL certificate file]
  • --key-file [relative/absolute path to SSL key file]
  • --ca-file [relative/absolute path to SSL certificate authority file]

Using npm run develop

Note: You can use relative or absolute paths with this command

Using the Gatsby CLI

Note: You can use relative or absolute paths with this command

Flag usage

Usage of the --ca-file flag is only required if your certificate is signed by a certificate authority.

If your certificate is self-signed, then do not include the --ca-file flag. Also, if you want your browser to trust a self-signed certificate, you will need to add it to your operating system (or browser’s, in Firefox’s case) root certificate store for your browser to trust it.

In most cases, the --https passed by itself is easier and more convenient to get local HTTPS.


Automatic certificates issued with the --https flag are issued to localhost by default, unless you have used the --host flag. If you have, a record in your hosts file will automatically be configured to point the defined host to 127.0.0.1. At this time, ip addresses defined by --host are not supported.