In a previous post, I showed how to use mix phx.gen.cert to set up HTTPS in Phoenix development. While that approach works in theory, in practice it's a minefield: OpenSSL 3.x generates PKCS12 bundles that macOS's security command rejects, browsers send cryptic Decode Error alerts, and manually trusting certificates in Keychain Access often has no effect at all.

There's a much better tool for this: mkcert.

What makes mkcert different?

mkcert creates a local Certificate Authority (CA) on your machine and registers it with macOS's system trust store, Firefox, and Chrome in one command. Any certificate you generate from it is automatically trusted — no manual Keychain fiddling required.

Step 1: Install mkcert and register the local CA

brew install mkcert
mkcert -install

The -install step is what makes everything work. It adds mkcert's root CA to your system keychain so all browsers trust it going forward.

Verify it landed:

security find-certificate -c "mkcert"

Step 2: Generate a certificate for localhost

From your Phoenix project root:

mkcert -cert-file priv/cert/selfsigned.pem \
       -key-file priv/cert/selfsigned_key.pem \
       localhost 127.0.0.1 ::1

This generates a certificate valid for localhost, 127.0.0.1, and ::1, signed by your local CA.

Step 3: Configure Phoenix for HTTPS

Update config/dev.exs:

config :your_app, YourAppWeb.Endpoint,
  https: [
    port: 4001,
    cipher_suite: :strong,
    certfile: "priv/cert/selfsigned.pem",
    keyfile: "priv/cert/selfsigned_key.pem"
  ],
  check_origin: false,
  code_reloader: true,
  debug_errors: true

Start your server:

mix phx.server

Visit https://localhost:4001 — no browser warnings, no certificate errors, no Keychain gymnastics.

What about the cert files in version control?

The generated priv/cert/ files are already in .gitignore when using mix phx.gen.cert, and should stay there with mkcert too. Each developer on your team runs mkcert -install and generates their own certificate locally.

Upgrading from the old approach

If you followed the previous post, you can replace the existing cert files in place — the Phoenix config stays the same since you're still pointing at priv/cert/selfsigned.pem and priv/cert/selfsigned_key.pem. Just regenerate them with mkcert and restart your server.