3a9c631526
While doing https://github.com/jupyterhub/jupyterhub/pull/2726, I realized we don't have a consistent way to format references inside the docs. I now have them be formatted to match the name of the file, but using `:` to separate them instead of `/` or `-`. `/` makes it ambiguous when using with markdown link syntax, as it could be a reference or a file. And using `-` is ambiguous, as that can be the name of the file itself. This PR does about half, I can do the other half later (unless someone else does).
3.6 KiB
Configuration Basics
This section contains basic information about configuring settings for a JupyterHub deployment. The Technical Reference documentation provides additional details.
This section will help you learn how to:
- generate a default configuration file,
jupyterhub_config.py - start with a specific configuration file
- configure JupyterHub using command line options
- find information and examples for some common deployments
(generate-config-file)=
Generate a default config file
On startup, JupyterHub will look by default for a configuration file,
jupyterhub_config.py, in the current working directory.
To generate a default config file, jupyterhub_config.py:
jupyterhub --generate-config
This default jupyterhub_config.py file contains comments and guidance for all
configuration variables and their default values. We recommend storing
configuration files in the standard UNIX filesystem location, i.e.
/etc/jupyterhub.
Start with a specific config file
You can load a specific config file and start JupyterHub using:
jupyterhub -f /path/to/jupyterhub_config.py
If you have stored your configuration file in the recommended UNIX filesystem
location, /etc/jupyterhub, the following command will start JupyterHub using
the configuration file:
jupyterhub -f /etc/jupyterhub/jupyterhub_config.py
The IPython documentation provides additional information on the config system that Jupyter uses.
Configure using command line options
To display all command line options that are available for configuration run the following command:
jupyterhub --help-all
Configuration using the command line options is done when launching JupyterHub.
For example, to start JupyterHub on 10.0.1.2:443 with https, you
would enter:
jupyterhub --ip 10.0.1.2 --port 443 --ssl-key my_ssl.key --ssl-cert my_ssl.cert
All configurable options may technically be set on the command line,
though some are inconvenient to type. To set a particular configuration
parameter, c.Class.trait, you would use the command line option,
--Class.trait, when starting JupyterHub. For example, to configure the
c.Spawner.notebook_dir trait from the command line, use the
--Spawner.notebook_dir option:
jupyterhub --Spawner.notebook_dir='~/assignments'
Configure for various deployment environments
The default authentication and process spawning mechanisms can be replaced, and specific authenticators and spawners can be set in the configuration file. This enables JupyterHub to be used with a variety of authentication methods or process control and deployment environments. Some examples, meant as illustrations, are:
- Using GitHub OAuth instead of PAM with OAuthenticator
- Spawning single-user servers with Docker, using the DockerSpawner
Run the proxy separately
This is not strictly necessary, but useful in many cases. If you use a custom proxy (e.g. Traefik), this is also not needed.
Connections to user servers go through the proxy, and not the hub itself. If the proxy stays running when the hub restarts (for maintenance, re-configuration, etc.), then user connections are not interrupted. For simplicity, by default the hub starts the proxy automatically, so if the hub restarts, the proxy restarts, and user connections are interrupted. It is easy to run the proxy separately, for information see the separate proxy page.