dance-lessons-coach/documentation/MKCERT.md

mkcert: Local HTTPS for Development

Overview

This document describes how to set up local HTTPS development certificates using mkcert.

OIDC providers reject http://localhost as a redirect URI by default for security reasons. To test OAuth 2.0 / OpenID Connect flows locally, the development server must be accessible via HTTPS. mkcert provides a zero-configuration local Certificate Authority that generates trusted certificates for localhost and custom domains.

This setup is a prerequisite for ADR-0028 Phase B (OpenID Connect Authorization Code flow).

Why mkcert

• Trusted locally: Certificates are automatically trusted by the system root store (macOS, Linux, Windows)
• No configuration: Single commands to create and install the CA
• Local-only: Certificates are valid only for localhost development, never exposed to production
• Industry standard: Widely adopted tool for local HTTPS development

Installation

macOS (Homebrew)

brew install mkcert
mkcert -install

The mkcert -install command creates and installs a local Certificate Authority in your system trust store.

Linux

See mkcert GitHub for distribution-specific instructions.

Windows

See mkcert GitHub for Windows installation.

Generate Certificates

Use the provided Make target to generate certificates for localhost development:

make cert

This runs the following command:

mkcert -cert-file ./certs/dev-cert.pem -key-file ./certs/dev-key.pem localhost 127.0.0.1 ::1

Output Files

File	Description
./certs/dev-cert.pem	TLS certificate for localhost, 127.0.0.1, and ::1
./certs/dev-key.pem	Private key for the certificate

Both files are created in the ./certs/ directory at the project root.

Use in Development

Once certificates are generated, start the server with TLS enabled:

./bin/server --tls-cert ./certs/dev-cert.pem --tls-key ./certs/dev-key.pem

Note

: The --tls-cert and --tls-key flags are not yet implemented — this is planned for ADR-0028 Phase B.4. The Makefile and certificate generation are prepared in advance so that when the server TLS support is added, the certificates are ready.

The server will then be accessible at:

• https://localhost:8080 (or the configured port)
• https://127.0.0.1:8080
• https://[::1]:8080

All OIDC callback URLs must use HTTPS with one of these hostnames.

Clean Up

To remove generated certificates:

make clean-cert

This deletes the entire ./certs/ directory.

.gitignore

The certs/ directory contains locally-generated certificates and must not be committed to version control.

Ensure certs/ is in your .gitignore. If it is not already present, add it:

echo "certs/" >> .gitignore

Cross-References

• ADR-0028: Passwordless authentication: magic link → OpenID Connect — Phase B describes the OIDC implementation that requires HTTPS
• mkcert GitHub Repository — Official documentation

Troubleshooting

"mkcert not found" when running make cert

Ensure mkcert is installed and available in your PATH. The Makefile checks for this and will display an error message if mkcert is not found.

Certificate not trusted by browser

Run mkcert -install again. On macOS, you may need to restart your browser completely (close all windows, not just tabs).

Port already in use

If another process is using the port (e.g., a non-TLS server on port 8080), stop that process first or configure the server to use a different port.

See Also

• make help — List all available Make targets
• documentation/API.md — API endpoints reference
• documentation/BDD_GUIDE.md — BDD testing guide