=================================
Serving h over SSL in development
=================================

If you want to annotate a site that's served over HTTPS then you'll need to
serve h over HTTPS as well, since the browser will refuse to load external
scripts (eg. H's bookmarklet) via HTTP on a page served via HTTPS.

To serve your local dev instance of h over HTTPS:

1. Generate a private key and certificate signing request::

    openssl req -newkey rsa:1024 -nodes -keyout .tlskey.pem -out .tlscsr.pem

2. Generate a self-signed certificate::

    openssl x509 -req -in .tlscsr.pem -signkey .tlskey.pem -out .tlscert.pem

3. Run the dev server with SSL::

    make devssl

4. Since the certificate is self-signed, you will need to instruct your browser to
   trust it explicitly by visiting https://localhost:5000 and selecting the option
   to bypass the validation error.

---------------
Troubleshooting
---------------

Insecure Response errors in the console
=======================================

The sidebar fails to load and you see ``net::ERR_INSECURE_RESPONSE`` errors in
the console.  You need to open https://localhost:5000 and tell the browser to allow
access to the site even though the certificate isn't known.


Server not found, the connection was reset
==========================================

When you're serving h over SSL in development making non-SSL requests to h
won't work.

If you get an error like **Server not found** or **The connection was reset**
in your browser (it varies from browser to browser), possibly accompanied by a
gunicorn crash with
``AttributeError: 'NoneType' object has no attribute 'uri'``, make sure that
you're loading https://localhost:5000 in your browser, not ``http://``.


WebSocket closed abnormally, code: 1006
=======================================

If you see the error message
**Error: WebSocket closed abnormally, code: 1006** in your browser,
possibly accompanied by another error message like
**Firefox can't establish a connection to the server at wss://localhost:5001/ws**,
this can be because you need to add a security exception to allow your browser
to connect to the websocket. Visit https://localhost:5001 in a browser tab and
add a security exception then try again.


403 response when connecting to WebSocket
=========================================

If your browser is getting a 403 response when trying to connect to the
WebSocket along with error messages like these:

* WebSocket connection to 'wss://localhost:5001/ws' failed: Error during WebSocket handshake: Unexpected response code: 403
* Check that your H service is configured to allow WebSocket connections from https://127.0.0.1:5000
* WebSocket closed abnormally, code: 1006
* WebSocket closed abnormally, code: 1001
* Firefox can't establish a connection to the server at wss://localhost:5001/ws

make sure that you're opening https://localhost:5000 in your browser and
*not* https://127.0.0.1:5000.