Automatic HTTPS

If you enable the Automatic HTTPS option when generating your codebase, the application can automatically obtain and renew TLS certificates in production using the acme/autocert package, and configure the server to use them.

Specifically:

• TLS certificates are automatically obtained from Let's Encrypt and renewed as needed.
• The application will listen on port 443 for HTTPS traffic, including responding to TLS-ALPN-01 challenges.
• The application will also listen on port 80 for HTTP traffic, redirecting all requests to HTTPS and serving responses to HTTP-01 challenges.

All the code controlling this lives in the serveAutoHTTPS() method in the cmd/api/server.go file.

Enabling automatic HTTPS

Automatic HTTPS is disabled by default.

For it to work correctly, there are two important prerequisites:

• The application must be running on a server with a publicly resolvable domain name. It will not work on localhost.
• The application must have the necessary privileges to listen on ports 80 and 443.

To enable automatic HTTPS, if you're using command-line flags for configuration, pass your publicly resolvable domain name in the --auto-https-domain flag when starting the application. For example:

$ go run ./cmd/api --auto-https-domain="www.example.org"

If you're using environment variables, set it in AUTO_HTTPS_DOMAIN, like so:

$ export AUTO_HTTPS_DOMAIN="www.example.org"

Let's Encrypt TLS Certificates

The TLS certificates generated by Let's Encrypt are valid for 90 days. They are automatically renewed 30 days before expiry, and cached in a certs directory relative to the running application.

It's important to be aware of the rate limits imposed by Let's Encrypt, and to avoid creating too many certificates too quickly for the same domain.

You can check which certificates have been issued for a domain using crt.sh.

Additional configuration settings

You can (and should!) configure a contact email address to be used for notifications about any problems with the Let's Encrypt certificates. If you're using command-line flags for configuration, pass the email address in the --auto-https-email flag when staring the application. If you're using environment variables, set the email address in AUTO_HTTPS_EMAIL.

You can also configure the application to use the Let's Encrypt staging environment (instead of production) for generating the TLS certificates. This has higher rate limits and is useful for testing, but it issues untrusted (but otherwise valid) TLS certificates.

To use the Let's Encrypt staging environment, if you're using command-line flags for configuration, start the application with the --auto-https-staging flag. For example:

$ go run ./cmd/api --auto-https-staging --auto-https-domain="www.example.org" 

Or if you're using environment variables, set AUTO_HTTPS_STAGING=true.