Added server deployment guide (#642)

doc/user_guide/index.rst

@@ -54,6 +54,9 @@ when needed.
 * `Templates <Templates.html>`_
    Learn how to compose multiple Panels into a custom HTML document.
 
+* `Server Deployment <Server_Deployment.html>`_
+   Step-by-step guides for deploying Panel apps locally, on a web server or on common cloud providers.
+
 Supplementary guides
 --------------------
 

examples/user_guide/Server_Deployment.ipynb

@@ -0,0 +1,196 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Panel is built on top of Bokeh, which provides a powerful [Tornado](https://www.tornadoweb.org/en/stable/) based web-server to communicate between Python and the browser. The bokeh server makes it possible to share the app or dashboard you have built locally, your own web server or using any of the numerous cloud providers. In this guide we will go through the details of deploying an app on a local system or cloud provider step by step."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## The server\n",
+    "\n",
+    "The Bokeh server is built on Tornado, which handles all of the communication between the browser and the backend. Whenever a user accesses the app or dashboard in a browser a new session is created which executes the app code and creates a new ``Document`` containing the models served to the browser where they are rendered by BokehJS.  \n",
+    "\n",
+    "<div style=\"margin-left: auto; margin-right: auto; display: block\">\n",
+    "<img src=\"https://bokeh.pydata.org/en/latest/_images/bokeh_serve.svg\"></img>\n",
+    "</div>\n",
+    "\n",
+    "### Accessing request arguments\n",
+    "\n",
+    "When a user accesses the Panel application via the browser they can optionally provide additional arguments in the URL. For example the query string ``?N=10`` will result in the following argument will be available on ``pn.state.session_args``: ``{'N': [b'10']}``. Such arguments may be used to customize the application."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Deployment\n",
+    "\n",
+    "As was covered in [Deploy and Export](Deploy_and_Export.ipynb) guide a Panel app, either in a notebook or a Python script, can be annotated with `.servable()` and then launched from the commandline using ``panel serve``. This launches a Tornado server on a specific port (defaulting to 5006) which you can access locally at ``https://localhost:{PORT}``. This is a good option for simple deployments on a local network.\n",
+    "\n",
+    "However many deployment scenarios have additional requirements around authentication, scaling, and uptime."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### SSH\n",
+    "\n",
+    "In some scenarios a standalone bokeh server may be running on remote host. In such cases, SSH can be used to “tunnel” to the server. In the simplest scenario, the Bokeh server will run on one host and will be accessed from another location, e.g., a laptop, with no intermediary machines.\n",
+    "\n",
+    "Run the server as usual on the remote host:\n",
+    "\n",
+    "Next, issue the following command on the local machine to establish an SSH tunnel to the remote host:\n",
+    "\n",
+    "```\n",
+    "ssh -NfL localhost:5006:localhost:5006 user@remote.host\n",
+    "```\n",
+    "\n",
+    "Replace user with your username on the remote host and remote.host with the hostname/IP address of the system hosting the Bokeh server. You may be prompted for login credentials for the remote system. After the connection is set up you will be able to navigate to localhost:5006 as though the Bokeh server were running on the local machine.\n",
+    "\n",
+    "The second, slightly more complicated case occurs when there is a gateway between the server and the local machine. In that situation a reverse tunnel must be established from the server to the gateway. Additionally the tunnel from the local machine will also point to the gateway.\n",
+    "\n",
+    "Issue the following commands on the remote host where the Bokeh server will run:\n",
+    "\n",
+    "```\n",
+    "nohup bokeh server &\n",
+    "ssh -NfR 5006:localhost:5006 user@gateway.host\n",
+    "```\n",
+    "\n",
+    "Replace user with your username on the gateway and gateway.host with the hostname/IP address of the gateway. You may be prompted for login credentials for the gateway.\n",
+    "\n",
+    "Now set up the other half of the tunnel, from the local machine to the gateway. On the local machine:\n",
+    "\n",
+    "```\n",
+    "ssh -NfL localhost:5006:localhost:5006 user@gateway.host\n",
+    "```\n",
+    "\n",
+    "Again, replace user with your username on the gateway and gateway.host with the hostname/IP address of the gateway. You should now be able to access the Bokeh server from the local machine by navigating to localhost:5006 on the local machine, as if the Bokeh server were running on the local machine. You can even set up client connections from a Jupyter notebook running on the local machine."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Reverse proxy\n",
+    "\n",
+    "If the goal is to serve an web application to the general Internet, it is often desirable to host the application on an internal network, and proxy connections to it through some dedicated HTTP server. For some basic configurations to set up a Bokeh server behind some common reverse proxies, including Nginx and Apache, refer to the [Bokeh documentation](https://bokeh.pydata.org/en/latest/docs/user_guide/server.html#basic-reverse-proxy-setup)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Cloud Deployments\n",
+    "\n",
+    "If you do not want to maintain your own web server and/or set up complex reverse proxies various cloud providers make it relatively simple to quickly deploy arbitrary apps on their system. In this section we will go through step-by-step to set up deployments on some of these providers.\n",
+    "\n",
+    "#### MyBinder\n",
+    "\n",
+    "Binder allows you to create custom computing environments that can be shared and used by many remote users. MyBinder is a public, free hosting option, with limited compute and memory resources, which will allow you to deploy your simple app quickly and easily.\n",
+    "\n",
+    "Here we will take you through the configuration to quickly set up a GitHub repository with notebooks containing Panel apps for deployment on MyBinder.org. As an example refer to the [Clifford demo repository](https://github.com/pyviz-demos/clifford).\n",
+    "\n",
+    "1. Create a GitHub repository and add the notebook or script you want to serve (in the example repository this is the clifford.ipynb file)\n",
+    "\n",
+    "2. Add an ``environment.yml`` which declares a conda environment with the dependencies required to run the app (refer to the [conda documentation](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-file-manually) to see how to declare your dependencies).\n",
+    "\n",
+    "3. Next, add a ``panelserverextension.py`` file to the repository containing a function which will launch the Panel server. Ensure you update the name of the notebook or script that you want to launch:\n",
+    "\n",
+    "```python\n",
+    "from subprocess import Popen\n",
+    "\n",
+    "def load_jupyter_server_extension(nbapp):\n",
+    "    \"\"\"serve the clifford.ipynb directory with bokeh server\"\"\"\n",
+    "    Popen([\"panel\", \"serve\", \"clifford.ipynb\", \"--allow-websocket-origin=*\"])\n",
+    "```\n",
+    "\n",
+    "4. Now add a ``postBuild`` file to the repository which activates the server extension:\n",
+    "\n",
+    "```\n",
+    "# enable nbserverproxy\n",
+    "jupyter serverextension enable --sys-prefix nbserverproxy\n",
+    "# install the panel server extension so that\n",
+    "# panel launches at startup\n",
+    "mv panelserverextension.py ${NB_PYTHON_PREFIX}/lib/python*/site-packages/\n",
+    "# enable panel extension\n",
+    "jupyter serverextension enable --sys-prefix panelserverextension\n",
+    "```\n",
+    "\n",
+    "5. Go to mybinder.org, enter the URL of your GitHub repository and hit ``Launch``\n",
+    "\n",
+    "6. mybinder.org will give you a link to the deployment, e.g. for the example app it is https://mybinder.org/v2/gh/panel-demos/clifford-interact/master. To visit the app simply append ``?urlpath=/proxy/5006/clifford`` where you should replace clifford with the name of the notebook or script you are serving.\n",
+    "\n",
+    "\n",
+    "#### Heroku\n",
+    "\n",
+    "Heroku makes deployment of arbitrary apps including Panel apps and dashboards very easy and provides a free tier to get you started. This makes it a great starting point for users not too familiar with web development and deployment.\n",
+    "\n",
+    "To get started working with Heroku [signup](https://signup.heroku.com) for a free account and [download and install the CLI](https://devcenter.heroku.com/articles/getting-started-with-python#set-up). Once you are set up follow the instructions to log into the CLI.\n",
+    "\n",
+    "1. Create a new Git repo (or to follow along clone the [minimal-heroku-demo](https://github.com/pyviz-demos/minimal-heroku-demo) GitHub repo)\n",
+    "\n",
+    "2. Add a Jupyter notebook or Python script which declares a Panel app or dashboard to the repository.\n",
+    "\n",
+    "3. Define a requirements.txt containing all the requirements for your app (including Panel itself). For the sample app the requirements are as minimal as:\n",
+    "\n",
+    "```\n",
+    "panel\n",
+    "hvplot\n",
+    "scikit-learn\n",
+    "```\n",
+    "\n",
+    "3. Define a `Procfile` which declares the command Heroku should run to serve the app. In the sample app the following command serves the `iris_kmeans.ipynb` example. The websocket origin should match the name of the app on Heroku ``app-name.herokuapp.com`` which you will declare in the next step:\n",
+    "\n",
+    "```\n",
+    "web: panel serve --address=\"0.0.0.0\" --port=$PORT iris_kmeans.ipynb --allow-websocket-origin=app-name.herokuapp.com\n",
+    "```\n",
+    "\n",
+    "4. Create a Heroku app using the CLI ensuring that the name matches the URL we declared in the previous step:\n",
+    "\n",
+    "```\n",
+    "heroku create app-name\n",
+    "```\n",
+    "\n",
+    "5. Push the app to heroku and wait until it is deployed.\n",
+    "\n",
+    "6. Visit the app at app-name.herokuapp.com\n",
+    "\n",
+    "Once you have deployed the app you might find that if your app is visited by more than one user at a time it will become unresponsive. In this case you can use the Heroku CLI [to scale your deployment](https://devcenter.heroku.com/articles/getting-started-with-python#scale-the-app).\n",
+    "\n",
+    "#### Anaconda Enterprise 5 (AE5)\n",
+    "\n",
+    "To be added.\n",
+    "\n",
+    "#### Amazon Web Services (AWS)\n",
+    "\n",
+    "To be added.\n",
+    "\n",
+    "#### Google Cloud Platform (GCP)\n",
+    "\n",
+    "To be added.\n",
+    "\n",
+    "#### Azure\n",
+    "\n",
+    "To be added.\n",
+    "\n",
+    "#### DigitalOcean\n",
+    "\n",
+    "To be added."
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}