CA Trust Setup

Simfra generates a root Certificate Authority (CA) on first startup. This CA issues TLS certificates for all Docker-backed services (load balancers, CloudFront distributions, API Gateway endpoints, etc.). To access these services over HTTPS without certificate warnings, import the root CA into your system trust store.

Prerequisites

  • Simfra running (the root CA is generated on first startup)
  • SIMFRA_DOCKER=true (CA trust is only needed for Docker-backed HTTPS services)

Where the Root CA Lives

The root CA certificate is generated at:

~/.simfra/ca/root-ca.crt

You can also download it from a running Simfra instance:

curl -o ca.crt http://localhost:4599/_simfra/ca/root.crt

The root CA persists across restarts. An intermediate CA is regenerated on each startup and is used to sign service certificates.

macOS

This covers Safari, Chrome, and all system tools (curl, wget, Go programs):

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain ~/.simfra/ca/root-ca.crt

To remove it later:

sudo security delete-certificate -c "Simfra Root CA" /Library/Keychains/System.keychain

Linux

System-wide (Debian/Ubuntu)

Covers curl, wget, Go, and most system tools:

sudo cp ~/.simfra/ca/root-ca.crt /usr/local/share/ca-certificates/simfra.crt
sudo update-ca-certificates

System-wide (RHEL/Fedora)

sudo cp ~/.simfra/ca/root-ca.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

Chrome on Linux

Chrome uses the NSS certificate database, separate from the system store:

certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n "Simfra Root CA" -i ~/.simfra/ca/root-ca.crt

Windows

Open PowerShell as Administrator:

Import-Certificate -FilePath "$env:USERPROFILE\.simfra\ca\root-ca.crt" -CertStoreLocation Cert:\LocalMachine\Root

This covers Edge, Chrome, and system tools. Firefox uses its own store (see below).

Firefox (All Platforms)

Firefox has its own certificate store on every platform:

  1. Open Settings > Privacy & Security
  2. Scroll to Certificates and click View Certificates
  3. Go to the Authorities tab
  4. Click Import and select ~/.simfra/ca/root-ca.crt
  5. Check Trust this CA to identify websites and click OK

AWS CLI

The AWS CLI validates TLS certificates. To use it with Simfra's HTTPS endpoints:

export AWS_CA_BUNDLE=~/.simfra/ca/root-ca.crt

Or add it to your AWS CLI config file (~/.aws/config):

[profile simfra]
ca_bundle = ~/.simfra/ca/root-ca.crt

Verify

After importing the CA, verify that HTTPS works without errors:

curl https://simfra.local:10200/

Or with an explicit CA path (if you have not imported it system-wide):

curl --cacert ~/.simfra/ca/root-ca.crt https://simfra.local:10200/

A successful response (or a normal HTTP error like 404) confirms trust is working. A TLS error like certificate verify failed means the CA is not yet trusted.

Next Steps