Certificates
Joppa's local certificate authority, per-domain certificates, reusing mkcert and getting the system to trust it.
The certificate authority
On first launch, Joppa creates a certificate authority (CA) specific to your user, “Joppa local CA”, valid for 10 years. Its private key stays on your machine, readable only by you, in Joppa’s ca/ folder. It can only sign for reserved local names (.test, .localhost, .internal, .local, .home.arpa, .example, .invalid): even copied, its key cannot impersonate a real site. A CA created by an older version of Joppa has no such limit; to replace it, delete the ca/ folder, restart Joppa and trust the new CA.
If you already use mkcert, Joppa reuses its CA (the one in $CAROOT, otherwise in mkcert’s default location). Joppa’s certificates are then accepted everywhere mkcert’s already were. Settings › Certificate authority shows which one is in use: “Joppa” or “mkcert (shared)”.
Domain certificates
Joppa signs a certificate on the fly, on the first connection to each domain. It covers the domain and its subdomains (myproject.test and *.myproject.test) and is valid for 397 days, the maximum browsers accept. There’s nothing to generate or renew.
Get the CA trusted
The browser only shows the padlock if the system trusts the CA. On the first launch, Joppa asks to approve it straight away: the system asks for your password, then Joppa adds the CA to its trusted list (on macOS: your login keychain and your trust settings). If you cancel, a banner at the top of the window offers Approve, and clicking CA … not trusted in the status bar opens the same button. Settings › Certificate authority shows the status, the same button (Approve the authority) and the equivalent command, to run once in a terminal if you prefer:
| System | Command | Check |
|---|---|---|
| macOS | sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "<rootCA.pem>" |
Automatic |
| Linux (Debian, Ubuntu) | sudo cp <rootCA.pem> /usr/local/share/ca-certificates/joppa-rootCA.crt && sudo update-ca-certificates |
Joppa can’t check it |
| Linux (Arch, Manjaro) | sudo cp <rootCA.pem> /etc/ca-certificates/trust-source/anchors/joppa-rootCA.crt && sudo update-ca-trust |
Joppa can’t check it |
| Linux (Fedora) | sudo cp <rootCA.pem> /etc/pki/ca-trust/source/anchors/joppa-rootCA.crt && sudo update-ca-trust |
Joppa can’t check it |
The status bar shows CA Joppa ok when it’s trusted, CA Joppa not trusted otherwise (clickable: it opens Approve).