This PR just adds a section to the documentation describing problems and solutions to serving jupyter from a public server that uses the Content-Security-Policy (CSP) header.

I ran into these problems using the latest docker containerjupyter/scipy-notebook to serve from a subdirectory on an existing webserver. I used a setup essentially likethe one described in the docs. I was able to access Jupyter through both the notebook interface and the jupyterlab interface, and the pages basically seemed to be working, in the sense that I could see menus and file listings, and so on.

However, actual connections to the kernel weren't working. For example, when I opened a new notebook, the kernel wouldn't start and I'd get the usual "Connection failed" message saying "A connection to the notebook server could not be established." Or in jupyterlab, everything would look fine, but when I'd try to execute a cell it would just hang. When I tried to open a terminal, nothing at all would happen; I wouldn't get a prompt or any message whatsoever. Looking at the javascript console, I saw lots of failed connections to WebSockets (which evidently go via thewss: scheme, orws: if you're not encrypting), with messages saying that our Contect-Security-Policy (CSP) was blocking those requests.

Now, because we have lots of different web apps running, we try to follow basic security guidelines — specificallyMozilla's guidelines, which includes a recommendation to use a restrictive CSP. I believe the problem is that our CSP includesdefault-src https: 'unsafe-inline', and that means thatwss: can't be used. My solution was to add

connect-src https: wss:

to the CSP, at least for the subdirectory where I'm serving jupyter. Now, everything's working great. (I also noticed that'unsafe-inline' is definitely necessary, so I mention that in the docs.)

I had a harder time than I should have figuring that out (because I was looking for 404s, and forgot to check the console for a while), so I'm hoping this at least shows up in search engines for people like me who just searched for the problem first.