run docusaurus locally with SSL if certs are provided (#366)

Author: jprusik

.env.example

@@ -0,0 +1,6 @@
+HTTPS=true
+
+# Generate via ./scripts/generate-certs, or mkcert
+# (see: https://docusaurus.io/docs/cli#enabling-https)
+SSL_CRT_FILE=ssl.crt
+SSL_KEY_FILE=ssl.key

.gitignore

@@ -10,6 +10,10 @@
 
 # Misc
 .DS_Store
+*.crt
+*.key
+*.pem
+.env
 .env.local
 .env.development.local
 .env.test.local

README.md

@@ -20,6 +20,24 @@ npm start
 This command starts a local development server and opens up a browser window. Most changes are
 reflected live without having to restart the server.
 
+### SSL
+
+By default, `npm start` will attempt to start your local instance with SSL enabled using
+certificates referenced in your local dotfile (`.env`).
+
+- copy the provided `.env.example` to `.env` and update the values as needed
+- (requires [OpenSSL](https://www.openssl.org/)) Generate your self-signed certs with
+  `npm run setup:ssl` and follow the instructions.
+  - Alternatively use [mkcert](https://github.com/FiloSottile/mkcert) to
+    [generate and add certs to your trust store](https://docusaurus.io/docs/cli#enabling-https)
+- run `npm start`!
+
+If the script fails to find your `.env` or the required values within, docusaurus will start
+normally without SSL.
+
+If you need to explicitly develop without SSL, simply delete your `.env` file or use the command
+`npm start:insecure` instead.
+
 ## Build
 
 ```bash

package.json

@@ -15,7 +15,9 @@
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
-    "start": "docusaurus start",
+    "start": "./scripts/docusaurus-start.sh",
+    "start:insecure": "docusaurus start",
+    "setup:ssl": "./scripts/generate-certs.sh",
     "build": "docusaurus build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",

scripts/docusaurus-start.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+ROOT_DIR=$(git rev-parse --show-toplevel)
+
+# shellcheck source=.env
+set -o allexport
+source $ROOT_DIR/.env
+set +o allexport
+
+npm run docusaurus start

scripts/generate-certs.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+
+ROOT_DIR=$(git rev-parse --show-toplevel)
+
+# Load .env values into the environment
+set -o allexport
+. "$ROOT_DIR/.env"
+set +o allexport
+
+openssl req -x509 -newkey rsa:4096 -keyout $SSL_KEY_FILE -out $SSL_CRT_FILE -sha256 -days 1826 -nodes \
+  -subj "/CN=localhost/O=Bitwarden Contributing Docs Local Development" \
+  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"
+
+chmod +rw $SSL_CRT_FILE
+chmod +rw $SSL_KEY_FILE
+
+printf "Certificate generated! When prompted, enter your password to update your system's secure store with the Certificate Authority.\n\n"
+printf "Alternatively, you can manually add it with:\n"
+
+# Mac OSX
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    printf "\e[30m\e[44m sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain $SSL_CRT_FILE \e[0m\n"
+
+    sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ssl.crt
+# If not Mac OS, assume *nix
+else
+    printf "\e[30m\e[44m sudo cp $SSL_CRT_FILE /usr/local/share/ca-certificates/ && sudo update-ca-certificates \e[0m\n\n"
+    printf "Important Note! Chromium doesn't use 'ca-certificates' on *nix. Instead it uses nssdb for cert storage, and depending on your configuration, may be in the shared system store at '\$HOME/.pki/nssdb', in Chromium's local snap store (e.g. '\$HOME/snap/chromium/current/.pki/nssdb'), or elsewhere. You will need to install the appropriate binary for your distro to run 'certutil -d sql:\$CHROMIUM_SECURE_STORE -A -t "CP,CP," -n DocsLocalDevelopmentSSL -i ./$SSL_CRT_FILE' from the project root."
+
+    sudo cp $SSL_CRT_FILE /usr/local/share/ca-certificates/
+    sudo update-ca-certificates
+fi