document security exception (#335)

README.md

@@ -49,6 +49,87 @@ a project setup from scratch :sparkles:.
   https://opencollective.com/choo
 ```
 
+## ⚠️  HTTPS Instructions
+When you first open up your application in a browser, you'll probably see a
+warning page about HTTPS connections being untrusted. No worries, this is
+entirely expected behavior. Follow the instructions below to solve this for
+your browser.
+
+<details>
+  <summary>
+    <b>How does this work?</b>
+  </summary>
+  For HTTPS to run on <code>localhost</code>, we must sign a TLS certificate
+  locally. This is better known as a "self-signed certificate". Browsers
+  actively check for certificates from uknown providers, and warn you (for good
+  reason!) In our case, however, it's safe to ignore.
+
+  HTTPS is needed for an increasing amount of APIs to work in the browser. For
+  example if you want to test HTTP/2 connections or use parts of the storage
+  API, you have no choice but to use an HTTPS connection on localhost. That's
+  why we try and make this work as efficiently, and securely as possible.
+
+  We generate a unique certificate for each Bankai installation. This means
+  that you'll only need to trust an HTTPS certificate for Bankai once. This
+  should be secure from remote attackers, because unless they have successfully
+  acquired access to your machine's filesystem, they won't be able to replicate
+  the certificate.
+</details>
+
+<details>
+  <summary>
+    <b>Firefox Instructions</b>
+  </summary>
+  <h3>Step 1</h3>
+
+  A wild security screen appears!. Click on "advanced".
+  <img src="/assets/firefox01.png" alt="firefox01">
+
+  <h3>Step 2</h3>
+  More details emerge! Click on "Add Exception".
+  <img src="/assets/firefox02.png" alt="firefox02">
+
+  <h3>Step 3</h3>
+  In the dropdown click "Confirm Security Exception".
+  <img src="/assets/firefox03.png" alt="firefox03">
+
+  <h3>Step 4</h3>
+  Success!
+  <img src="/assets/firefox04.png" alt="firefox04">
+</details>
+
+<details>
+  <summary>
+    <b>Chrome Instructions</b>
+  </summary>
+  Click the "more details" dropdown, then click "proceed". Pull Request for
+  screenshots welcome!
+</details>
+
+<details>
+  <summary>
+    <b>Safari Instructions</b>
+  </summary>
+  <h3>Step 1</h3>
+  A wild security screen appears! Click "Show Certificate".
+  <img src="/assets/safari01.png" alt="safari01">
+
+  <h3>Step 2</h3>
+  More details emerge! Check "Always trust 'localhost'…".
+  <img src="/assets/safari02.png" alt="safari02">
+
+  <h3>Step 3</h3>
+  The box is checked! Click "Continue".
+  <img src="/assets/safari03.png" alt="safari03">
+
+  <h3>Step 4</h3>
+  A box is asking you for your crendentials. Fill them in, and hit "Enter".
+
+  <h3>Step 5</h3>
+  Success!
+  <img src="/assets/safari04.png" alt="safari04">
+</details>
+
 ## Optimizations
 Bankai applies lots of optimizations to projects. Generally you won't need to
 care how we do this: it's lots of glue code, and not necessarily pretty. But it