diff --git a/docs/source/services.md b/docs/source/services.md index eafee5e9..6190bed0 100644 --- a/docs/source/services.md +++ b/docs/source/services.md @@ -1,70 +1,115 @@ -# JupyterHub services +# Services -JupyterHub 0.7 adds the notion of Services. -A Service is a process that interacts with the Hub REST API. -Services may perform actions such as shutting down user servers that have been idle for some time, -or registering additional web servers that should also use the Hub's authentication -and be served behind the Hub's proxy. -There are two main characteristics of services: +With version 0.7, JupyterHub adds support for 'Services'. -1. Is it **managed** by JupyterHub? -2. Does it have a web server that should be added to the proxy? -If a `command` is specified for launching the service, it will be started and managed by the Hub. -If a `url` is specified for where the service runs its own webserver, -it will be added to the Hub's proxy at `/service/:service-name`. +## JupyterHub's definition of a Service -## Managed services +When working with JupyterHub, a Service is defined as a process that interacts +with the Hub's REST API. A Service may perform a specialized action or +specific task. For example, each of these tasks can be a unique Service: -**Managed** services are services that the Hub starts and is responsible for. -These can only be local subprocesses of the Hub, -and the Hub will take care of starting these processes and restarting them if they stop. +- shutting down individuals' single user notebook servers that have been idle + for some time +- registering additional web servers which should use the Hub's authentication + and be served behind the Hub's proxy. -While there are similarities with notebook Spawners, -there are no plans to support the same spawning abstractions as notebook. -If you want to run these services in docker or other environments, -you can register it as an external service below. +Two main characteristics help define a Service: -A managed service is characterized by the `command` specified for launching the service. +1. Is the *Service* **managed** by JupyterHub? +2. Does the *Service* have a web server that should be added to the proxy's + table? +Currently, a Service may be either a 'Hub-Managed Service' which is managed by +JupyterHub, or an 'Externally-Managed Service' which runs its own web server and +communicates operation instructions via the Hub's API. + +### Properties of a Service + +If a `command` is specified for launching the Service, the Service will be +started and managed by the Hub. + +If a `url` is specified for where the Service runs its own web server, +JupyterHub will add the Service to the Hub's proxy at +`/service/:service-name`. + +## Hub-Managed Service + +If a Service is started by the Hub and the Hub is responsible for the +Service's actions, the Service is referred to as a **Hub-Managed Service** of +JupyterHub. Hub-Managed Services can only be a local subprocesses of the Hub. The +Hub will take care of starting these processes and restarting them if they +stop. + +While Hub-Managed Services share some similarities with notebook Spawners, +there are no plans for Hub-Managed Services to support the same spawning +abstractions as a notebook Spawner. If you wish to run Services in +Docker or other deployment environments, the Service can be registered as an +Externally-Managed Service, as described below. + +### Launching a Hub-Managed Service + +A Hub-Managed Service is characterized by its specified `command` for launching +the Service. For example, the configuration of a 'cull idle' notebook server +Hub-Managed Service would include the Service name, admin permissions, and the +`command` to launch the Service which will cull idle servers after a timeout +interval: ```python c.JupyterHub.services = [ { 'name': 'cull-idle', 'admin': True, - 'command': ['python', '/path/to/cull-idle.py', '--interval'] + 'command': ['python', '/path/to/cull-idle.py', '--timeout'] } ] ``` -In addition to `command`, managed services can take additional optional parameters, -to describe the environment in which to start the process: -- `env: dict` additional environment variables for the service. +In addition to the `command` to launch the Service, a Hub-Managed Service may also +be configured with additional optional parameters, which describe the +environment needed to start the process: + +- `env: dict` additional environment variables for the Service. - `user: str` name of the user to run the server as if different from the Hub. - Requires Hub to be root. -- `cwd: path` directory in which to run the service, if different from the Hub directory. + Requires Hub to be root. +- `cwd: path` directory in which to run the Service, if different from the + Hub directory. -When the service starts, the Hub will pass the following environment variables: +The Hub will pass the following environment variables to launch the Service: ``` -JUPYTERHUB_SERVICE_NAME: the name of the service ('cull-idle' above) +JUPYTERHUB_SERVICE_NAME: the name of the service +JUPYTERHUB_API_TOKEN: API token assigned to the service +JUPYTERHUB_API_URL: URL for the JupyterHub API (default, http://127.0.0.1:8080/hub/api) +JUPYTERHUB_BASE_URL: Base URL of the Hub (https://mydomain[:port]/) +JUPYTERHUB_SERVICE_PREFIX: URL path prefix of this service (/services/:service-name/) +``` + +For the previous example, these environment variables would be passed when +starting the 'cull idle' Service: + +``` +JUPYTERHUB_SERVICE_NAME: 'cull-idle' JUPYTERHUB_API_TOKEN: API token assigned to the service -JUPYTERHUB_API_URL: URL for the JupyterHub API (http://127.0.0.1:8080/hub/api) -JUPYTERHUB_BASE_URL: Base URL of the Hub (https://mydomain[:port]/) -JUPYTERHUB_SERVICE_PREFIX: URL path prefix of this service (/services/cull-idle/) +JUPYTERHUB_API_URL: http://127.0.0.1:8080/hub/api +JUPYTERHUB_BASE_URL: https://mydomain[:port] +JUPYTERHUB_SERVICE_PREFIX: /services/cull-idle/ ``` -## External services +## Externally-Managed Services -You can use your own service management tools, such as docker or systemd, to manage JupyterHub services. -These are not subprocesses of the Hub, and you must tell JupyterHub what API token the service is using to perform its API requests. -Each service will need a unique API token because the Hub authenticates each API request, -identifying the originating service or user. +To meet your specific use case needs, you may use your own service management +tools, such as Docker or systemd, to manage a JupyterHub Service. +These Externally-Managed Services, unlike Hub-Managed Services, are not subprocesses of +the Hub. You must tell JupyterHub which API token the Externally-Managed Service is +using to perform its API requests. Each Externally-Managed Service will need a unique +API token because the Hub authenticates each API request and the API token is +used to identify the originating Service or user. -An example of an externally managed service with admin access and running its own web server: +A configuration example of an Externally-Managed Service with admin access and running its +own web server is: ```python c.JupyterHub.services = [ @@ -85,4 +130,5 @@ TODO TODO -JupyterHub 0.7 introduces some utiltiies for you to use that allow you to use the Hub's authentication mechanism. \ No newline at end of file +JupyterHub 0.7 introduces some utilities to use the Hub's authentication +mechanism. \ No newline at end of file