Server Configuration#
The Panel server can be launched either from the commandline (using panel serve) or programmatically (using panel.serve()). In this guide we will discover how to run and configure server instances using these two options.
Launching a server on the commandline#
Once the app is ready for deployment it can be served using the Bokeh server. For a detailed breakdown of the design and functionality of Bokeh server, see the Bokeh documentation. The most important thing to know is that Panel (and Bokeh) provide a CLI command to serve a Python script, app directory, or Jupyter notebook containing a Bokeh or Panel app. To launch a server using the CLI, simply run:
panel serve app.ipynb
Alternatively you can also list multiple apps:
panel serve app1.py app2.ipynb
or even serve a number of apps at once:
panel serve apps/*.py
For development it can be particularly helpful to use the --autoreload option to panel serve as that will automatically reload the page whenever the application code or any of its imports change.
The panel serve command has the following options:
positional arguments:
DIRECTORY-OR-SCRIPT The app directories or scripts or notebooks to serve
(serve empty document if not specified)
optional arguments:
-h, --help show this help message and exit
--port PORT Port to listen on
--address ADDRESS Address to listen on
--log-level LOG-LEVEL
One of: trace, debug, info, warning, error or critical
--log-format LOG-FORMAT
A standard Python logging format string (default:
'%(asctime)s %(message)s')
--log-file LOG-FILE A filename to write logs to, or None to write to the
standard stream (default: None)
--args ... Any command line arguments remaining are passed on to
the application handler
--show Open server app(s) in a browser
--allow-websocket-origin HOST[:PORT]
Public hostnames which may connect to the Bokeh
websocket
--prefix PREFIX URL prefix for Bokeh server URLs
--keep-alive MILLISECONDS
How often to send a keep-alive ping to clients, 0 to
disable.
--check-unused-sessions MILLISECONDS
How often to check for unused sessions
--unused-session-lifetime MILLISECONDS
How long unused sessions last
--stats-log-frequency MILLISECONDS
How often to log stats
--mem-log-frequency MILLISECONDS
How often to log memory usage information
--use-xheaders Prefer X-headers for IP/protocol information
--ssl-certfile CERTFILE
Absolute path to a certificate file for SSL termination
--ssl-keyfile KEYFILE
Absolute path to a private key file for SSL termination
--session-ids MODE One of: unsigned, signed or external-signed
--auth-module AUTH_MODULE
Absolute path to a Python module that implements auth hooks
--enable-xsrf-cookies
Whether to enable Tornado support for XSRF cookies.
All PUT, POST, or DELETE handlers must be properly
instrumented when this setting is enabled.
--exclude-headers EXCLUDE_HEADERS [EXCLUDE_HEADERS ...]
A list of request headers to exclude from the session
context (by default all headers are included).
--exclude-cookies EXCLUDE_COOKIES [EXCLUDE_COOKIES ...]
A list of request cookies to exclude from the session
context (by default all cookies are included).
--include-headers INCLUDE_HEADERS [INCLUDE_HEADERS ...]
A list of request headers to make available in the
session context (by default all headers are included).
--include-cookies INCLUDE_COOKIES [INCLUDE_COOKIES ...]
A list of request cookies to make available in the
session context (by default all cookies are included).
--session-ids MODE One of: unsigned, signed, or external-signed
--index INDEX Path to a template to use for the site index or
an app to serve at the root.
--disable-index Do not use the default index on the root path
--disable-index-redirect
Do not redirect to running app from root path
--num-procs N Number of worker processes for an app. Using 0 will
autodetect number of cores (defaults to 1)
--num-threads N Number of threads to launch in a ThreadPoolExecutor which
Panel will dispatch events to for concurrent execution on
separate cores (defaults to None).
--warm Whether to execute scripts on startup to warm up the server.
--autoreload
Whether to automatically reload user sessions when the
application or any of its imports change.
--static-dirs KEY=VALUE [KEY=VALUE ...]
Static directories to serve specified as key=value
pairs mapping from URL route to static file directory.
--dev [FILES-TO-WATCH [FILES-TO-WATCH ...]]
Enable live reloading during app development.By
default it watches all *.py *.html *.css *.yaml
filesin the app directory tree. Additional files can
be passedas arguments. NOTE: This setting only works
with a single app.It also restricts the number of
processes to 1.
--session-token-expiration N
Duration in seconds that a new session token is valid
for session creation. After the expiry time has elapsed,
the token will not be able create a new session
(defaults to seconds).
--websocket-max-message-size BYTES
Set the Tornado websocket_max_message_size value
(defaults to 20MB) NOTE: This setting has effect ONLY
for Tornado>=4.5
--websocket-compression-level LEVEL
Set the Tornado WebSocket compression_level
--websocket-compression-mem-level LEVEL
Set the Tornado WebSocket compression mem_level
--oauth-provider OAUTH_PROVIDER
The OAuth2 provider to use.
--oauth-key OAUTH_KEY
The OAuth2 key to use
--oauth-secret OAUTH_SECRET
The OAuth2 secret to use
--oauth-redirect-uri OAUTH_REDIRECT_URI
The OAuth2 redirect URI
--oauth-extra-params OAUTH_EXTRA_PARAMS
Additional parameters to use.
--oauth-jwt-user OAUTH_JWT_USER
The key in the ID JWT token to consider the user.
--oauth-encryption-key OAUTH_ENCRYPTION_KEY
A random string used to encode the user information.
--rest-provider REST_PROVIDER
The interface to use to serve REST API
--rest-endpoint REST_ENDPOINT
Endpoint to store REST API on.
--rest-session-info
Whether to serve session info on the REST API
--session-history SESSION_HISTORY
The length of the session history to record.
--setup
Path to a setup script to run before server starts, e.g. to cache data or set up scheduled tasks.
--liveness
Whether to add an endpoint to confirm liveness of the server and optionally various endpoints
(defaults to /liveness but endpoint can be controlled with --liveness-endpoint)
--liveness-endpoint
The endpoint to serve the liveness API at.
--admin
Whether to add an admin panel.
--admin-log-level
One of: debug, info, warning, error or critical
--profiler PROFILER
The profiler to use by default, e.g. pyinstrument or snakeviz.
To turn a notebook into a deployable app simply append .servable() to one or more Panel objects, which will add the app to Bokeh’s curdoc, ensuring it can be discovered by Bokeh server on deployment. In this way it is trivial to build dashboards that can be used interactively in a notebook and then seamlessly deployed on Bokeh server.
When called on a notebook, panel serve first converts it to a python script using nbconvert.PythonExporter(), albeit with IPython magics stripped out. This means that non-code cells, such as raw cells, are entirely handled by nbconvert and may modify the served app.
Launching a server dynamically#
The CLI panel serve command described below is usually the best approach for deploying applications. However when working on the REPL or embedding a Panel/Bokeh server in another application it is sometimes useful to dynamically launch a server, either using the .show method or using the pn.serve function.
Previewing an application#
Working from the command line will not automatically display rich representations inline as in a notebook, but you can still interact with your Panel components if you start a Bokeh server instance and open a separate browser window using the show method. The method has the following arguments:
port: int (optional)
Allows specifying a specific port (default=0 chooses an arbitrary open port)
websocket_origin: str or list(str) (optional)
A list of hosts that can connect to the websocket.
This is typically required when embedding a server app in
an external-facing web site.
If None, "localhost" is used.
threaded: boolean (optional, default=False)
Whether to launch the Server on a separate thread, allowing
interactive use.
title : str
A string title to give the Document (if served as an app)
**kwargs : dict
Additional keyword arguments passed to the bokeh.server.server.Server instance.
To work with an app completely interactively you can set threaded=True which will launch the server on a separate thread and let you interactively play with the app.
The .show call will return either a Bokeh server instance (if threaded=False) or a StoppableThread instance (if threaded=True) which both provide a stop method to stop the server instance.
Serving multiple apps#
If you want to serve more than one app on a single server you can use the pn.serve function. By supplying a dictionary where the keys represent the URL slugs and the values must be either Panel objects or functions returning Panel objects you can easily launch a server with a number of apps, e.g.:
import panel as pn
pn.serve({
'markdown': '# This is a Panel app',
'json': pn.pane.JSON({'abc': 123})
})
Note that when you serve an object directly all sessions will share the same state, i.e. the parameters of all components will be synced across sessions such that the change in a widget by one user will affect all other users. Therefore you will usually want to wrap your app in a function, ensuring that each user gets a new instance of the application:
def markdown_app():
return '# This is a Panel app'
def json_app():
return pn.pane.JSON({'abc': 123})
pn.serve({
'markdown': markdown_app,
'json': json_app
})
You can customize the HTML title of each application by supplying a dictionary where the keys represent the URL slugs and the values represent the titles, e.g.:
pn.serve({
'markdown': '# This is a Panel app',
'json': pn.pane.JSON({'abc': 123})
}, title={'markdown': 'A Markdown App', 'json': 'A JSON App'}
)
The pn.serve accepts a number of arguments:
panel: Viewable, function or {str: Viewable or function}
A Panel object, a function returning a Panel object or a
dictionary mapping from the URL slug to either.
port: int (optional, default=0)
Allows specifying a specific port
address: str
The address the server should listen on for HTTP requests.
websocket_origin: str or list(str) (optional)
A list of hosts that can connect to the websocket.
This is typically required when embedding a server app in
an external web site.
If None, "localhost" is used.
loop: tornado.ioloop.IOLoop (optional, default=IOLoop.current())
The tornado IOLoop to run the Server on
show: boolean (optional, default=False)
Whether to open the server in a new browser tab on start
start: boolean(optional, default=False)
Whether to start the Server
title: str or {str: str} (optional, default=None)
An HTML title for the application or a dictionary mapping
from the URL slug to a customized title
verbose: boolean (optional, default=True)
Whether to print the address and port
location: boolean or panel.io.location.Location
Whether to create a Location component to observe and
set the URL location.
kwargs: dict
Additional keyword arguments to pass to Server instance
Static file hosting#
Whether you’re launching your application using panel serve from the commandline or using pn.serve in a script you can also serve static files. When using panel serve you can use the --static-dirs argument to specify a list of static directories to serve along with their routes, e.g.:
panel serve some_script.py --static-dirs assets=./assets
This will serve the ./assets directory on the servers /assets route. Note however that the /static route is reserved internally by Panel.
Similarly when using pn.serve or panel_obj.show the static routes may be defined as a dictionary, e.g. the equivalent to the example would be:
pn.serve(panel_obj, static_dirs={'assets': './assets'})