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.