Configure TLS

This guide walks you through setting up local Certificate Authority (CA) certificates for development environments.

Install mkcert

First, install mkcert and its dependencies:

macOS

brew install mkcert
brew install nss  # if you use Firefox
bash

Linux

sudo apt install libnss3-tools
sudo apt install mkcert
bash

Create and Install Local CA

  1. Create and install the local CA in the system trust store:
mkcert -install
bash

The CA files will be stored in:

  • macOS: ~/Library/Application Support/mkcert
  • Linux: ~/.local/share/mkcert
  1. Generate certificates:
# Create certificates for localhost
mkcert localhost

# This will generate:
# - localhost.pem (certificate)
# - localhost-key.pem (private key)
bash
  1. Find your root CA files:
# Show the location of your root CA files
mkcert -CAROOT

# You'll need:
# - rootCA.pem (CA certificate)
# - rootCA-key.pem (CA private key)
bash

Configure FeatureMeshd

  1. Update your config.yaml to use the CA certificates:
tls:
  certificate_chain: "/certs/rootCA.pem"    # Root CA certificate
  private_key: "/certs/rootCA-key.pem"      # Root CA private key
yaml
  1. Update your docker-compose.yml to mount the certificates:
services:
  featuremeshd:
    volumes:
      # For Linux:
      - ${HOME}/.local/share/mkcert/rootCA.pem:/certs/rootCA.pem
      - ${HOME}/.local/share/mkcert/rootCA-key.pem:/certs/rootCA-key.pem

      # For macOS:
      # - ${HOME}/Library/Application Support/mkcert/rootCA.pem:/certs/rootCA.pem
      # - ${HOME}/Library/Application Support/mkcert/rootCA-key.pem:/certs/rootCA-key.pem
yaml

Troubleshooting

Common issues:

  1. Certificate not trusted

    • Ensure mkcert was installed correctly
    • Run mkcert -install again
    • Restart your browser

  2. Certificate files not found

    • Use mkcert -CAROOT to verify the location
    • Check file permissions
    • Ensure paths in docker-compose.yml match your OS

  3. Firefox issues

    • Install nss package
    • Run mkcert -install again
Suggest changes to this page
Last update at: 2025/11/06 07:00:15
Last updated: 2025-11-06 07:00:51