While developing clojurescript web apps, you may require that the development http servershadow-cljs operate with SSL/TLS to serve up HTTPS, not just HTTP.

This is particuarly true if you need to test things out on an iPhone or Android phone but still run with the development server so you can iterated changes just as quick as when you are working with desktop clients.

Its a bit tricky to get everything lined up to make SSL/TLS work locally as Apple (and I presume other browsers) no longer support self-signed certificates for HTTPS servers. So you need a private CA and a certificate generated from the private CA.

This is a guide to set up:

• A Private Certificate Authority (CA)
• A Server Certificate for your shadow-cljs development server
• How to configure shadow-cljs.edn for SSL
• How to install the CA Root Certificate on other clients (like an iPhone) so they can access the shadow-cljs servers

**NOTE: This server / CA / Certificates should never be used in production or in any particularly public way. It’s not secure. We’re doing this to get around the normal browser / server security just for local development.

Install mkcert

See the following for more info or how to install on Linux:GitHub - FiloSottile/mkcert

Install mkcert on macOS

> brewinstallmkcert> brewinstallnss# if you use Firefox

Create a local CA to be used by mkcert and clients

> mkcert-installCreated a newlocalCA 💥Sudo password:ThelocalCA is now installedinthe system trust store! ⚡️ThelocalCA is now installedinthe Firefox trust store(requires browser restart)! 🦊ThelocalCA is now installedinJava's trust store! ☕️

Create a pkcs12 certificate

Easiest to do this in the directory you are running the shadow-cljs project.
Create a subdirectoryssl at the same level as shadow-cljs (top level of the repo usually) and cd intossl

❯cd ~/work/my-project❯lsMakefile        RELEASE_TAG     bin             dev             package.json    shadow-cljs.edntestREADME.org      amplify         deps.edn        node_modules    resources       src             yarn.lock❯mkdirssl❯cdssl

Create the certificate that the shadow-cljs servers will use as their server certificates. You want to specify all the domains and IPs that would be associated with the certificate and the way you will access the server.
In my case my iMac has two interfaces plus localhost. One interface is the Ethernet, the other is the wifi. And just to be safe, I’m putting in their IPv6 addresses as well.

❯ mkcert-pkcs12 discovery.local localhost  192.168.20.10 192.168.20.11 127.0.0.1 ::1 fd95:cb6f:7955:0:1878:b8b5:1b3b:ad27 fd95:cb6f:7955:0:4cd:c922:d1b3:2eb5Created a new certificate validforthe following names 📜 -"discovery.local" -"localhost" -"192.168.20.10" -"192.168.20.11" -"127.0.0.1" -"::1" -"fd95:cb6f:7955:0:1878:b8b5:1b3b:ad27" -"fd95:cb6f:7955:0:4cd:c922:d1b3:2eb5"The PKCS#12 bundle is at"./discovery.local+7.p12" ✅The legacy PKCS#12 encryption password is the often hardcoded default"changeit" ℹ️It will expire on 20 January 2024 🗓

Install the cert into the keystore

NOTE:The passwords you use here should not be used anywhere else, particularly on public services. They do not have to be super secret, great passwords as they will be in the clear in your shadow-cljs.

You will create a local Java JKS Keystore inssl to be used by shadow-cljs servers

• Destination Password: This will be the password specified in shadow-cljs.edn to gain access to the keystore. Our example will besuper-secret
• Source keystore password: The password thatmkcert used to generate the Server Certificate and thus the password of the Server Certificate. I could not find a way to specify it. It defaults tochangeit

❯ keytool-importkeystore-destkeystore keystore.jks-srcstoretype PKCS12-srckeystore discovery.local+7.p12Importing keystore discovery.local+7.p12 to keystore.jks...Enter destination keystore password: super-secretRe-enter new password: super-secretEntersourcekeystore password: changeitEntryforalias1 successfully imported.Importcommandcompleted:  1 entries successfully imported, 0 entries failed or cancelled

Configure shadow-cljs.edn to enable SSL

Mainly need to add an:ssl coda to the start of theshadow-cljs.edn

{:depstrue:nrepl{:port8777}:ssl{:keystore"ssl/keystore.jks":password"retold-fever"}:dev-http{8020{:root"resources/public"}}...restofyourshadow-cljs.ednfile...

No need to specify the hostnames. In fact that will limit access to IP addresses that resolve to that name which may be incorrect.
More info on the:ssl configuration atShadow CLJS User’s Guide: SSL

[Re]start your shadow-cljs watch process and it should say something like the following at some point in its startup wherehttps is the protocol shown for the http and shadow-cljs servers:

...shadow-cljs - HTTP server available at https://localhost:8020shadow-cljs - server version: 2.15.8 running at https://localhost:9631shadow-cljs - nREPL server started on port 8777shadow-cljs - watching build :app...

Assuming you set the certificate to support any other domain names and IP addresses associated with your computer running this, they will also work as the host address in your client URL accessing this server. But only if running on the same machine as this server.

If you want to make another device (like an iPhone or another computer) access this server, follow the next steps.

Export the Root CA of your Private CA to other Clients

In order for other machines on your LAN to access the shadow-cljs server running with the Private CA and Server certificate set up in the earlier steps, you will need to export the Root CA from that machine to these other clients.

Find the location of the Root Certificate of the Private CA

When you ranmkcert install it created the root certificates of the Private CA and stashed them somewhere appropriate for your system. You can find out where with the command:

❯ mkcert-CAROOT/Users/rberger/Library/Application Support/mkcert❯ls'/Users/rberger/Library/Application Support/mkcert'rootCA-key.pem rootCA.pem

You will want to copy therootCA.pem to other clients that would access the shadow-cljs servers.

For transferring to other Macs or iOS devices

open'/Users/rberger/Library/Application Support/mkcert'

Which will open a finder window with the directory where these pem files are:

And then select AirDrop to send them to other macOS or iOS devices
Otherwise you can email it or send the file some other way to a destination device.

Install the Private CA Root Cert on iOS device

• Once you send the Cert to an iOS device, you will get a message
  

• Select iPhone and then select Close:
  

• Go to Settings and you’ll see the a new optionProfile Downloaded Click on that and the go thru the rest of the dialogs agreeing to Install the downloaded profile.

• After completing all the install dialogs, this client should be ready to connect to the shadow-cljs using https.