JupyterHub

https://jupyterhub.readthedocs.io/en/stable/
Admin
JupyterHub is a multi-user server that spawns, manages, and proxies multiple instances of...
Tokens:194,935
Snippets:2,733
Trust Score:9.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Kernelspecs System-Wide

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/howto/configuration/config-user-env.md.txt

Example commands to install Python 2 and Python 3 kernelspecs system-wide to /usr/local.

```bash
/path/to/python3 -m ipykernel install --prefix=/usr/local
/path/to/python2 -m ipykernel install --prefix=/usr/local
```

--------------------------------

### Start configurable-http-proxy as a separate service

Source: https://jupyterhub.readthedocs.io/en/stable/howto/separate-proxy.html

Example command line arguments for launching the proxy manually. Ensure the API and target URLs match the hub's configuration and the authentication token is set via environment variables.

```bash
$ configurable-http-proxy --ip=127.0.0.1 --port=8000 --api-ip=127.0.0.1 --api-port=8001 --default-target=http://localhost:8081 --error-target=http://localhost:8081/hub/error
```

--------------------------------

### Install Documentation Dependencies

Source: https://jupyterhub.readthedocs.io/en/stable/contributing/docs.html

Install the necessary Python packages to build the documentation locally.

```bash
python3 -m pip install -r docs/requirements.txt
python3 -m pip install sphinx-autobuild
```

--------------------------------

### Install Configurable HTTP Proxy Locally

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/contributing/setup.md.txt

Install configurable-http-proxy locally if a global install fails due to permissions. Ensure the local bin directory is added to your PATH.

```bash
npm install configurable-http-proxy
export PATH=$PATH:$(pwd)/node_modules/.bin
```

--------------------------------

### Install configurable-http-proxy

Source: https://jupyterhub.readthedocs.io/en/stable/contributing/setup.html

Install the required proxy server globally, locally, or via conda.

```bash
npm install -g configurable-http-proxy
```

```bash
npm install configurable-http-proxy
export PATH=$PATH:$(pwd)/node_modules/.bin
```

```bash
conda install configurable-http-proxy
```

--------------------------------

### Start Server

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/tutorial/server-api.md.txt

Initiate the launch of a user's server. This endpoint can be used to start the default server or a named server for a given user. The response indicates whether the server is immediately ready or has started the spawning process.

```APIDOC
## POST /hub/api/users/:username/servers/[:servername]

### Description
Starts a server for a given user. If `servername` is omitted, it starts the default server.

### Method
POST

### Endpoint
/hub/api/users/:username/servers/[:servername]

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user for whom to start the server.
- **servername** (string) - Optional - The name of the server to start. If omitted, the default server is started.

### Response
#### Success Response (201 Created)
Indicates the launch completed and the server is ready and available immediately.

#### Success Response (202 Accepted)
Indicates the server has begun launching but is not immediately ready. The server will show `pending: 'spawn'` and requires polling or using the progress API to determine readiness.
```

--------------------------------

### Install sudospawner

Source: https://jupyterhub.readthedocs.io/en/stable/howto/configuration/config-sudo.html

Install the sudospawner package using pip.

```bash
sudo python3 -m pip install sudospawner
```

--------------------------------

### Example Resource Requests and Limits

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/explanation/capacity-planning.md.txt

A sensible starting point for CPU and memory requests and limits in a JupyterHub deployment. Adjust memory based on expected computations like machine learning or data analysis.

```yaml
request:
  cpu: 0.5
  mem: 2G
limit:
  cpu: 1
  mem: 2G
```

--------------------------------

### Install and Enable JupyterLab

Source: https://jupyterhub.readthedocs.io/en/stable/faq/troubleshooting.html

Install the JupyterLab extension system-wide and configure the spawner to use it as the default interface.

```bash
python3 -m pip install jupyterlab
jupyter serverextension enable --py jupyterlab --sys-prefix
```

```python
c.Spawner.default_url = '/lab'
```

--------------------------------

### Install Node.js Dependencies

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/contributing/setup.md.txt

Install necessary Node.js dependencies to compile CSS. This is often required if the 'lessc' command is not found during setup.

```bash
npm install
```

--------------------------------

### start()

Source: https://jupyterhub.readthedocs.io/en/stable/reference/api/spawner.html

Starts the single-user server. This method is a coroutine that returns the IP address and port where the Hub can connect to the server.

```APIDOC
## _async _start()

### Description
Starts the single-user server.

### Returns
- **(str, int)** - The (ip, port) where the Hub can connect to the server.
```

--------------------------------

### Start a server with POST /hub/api/users/:username/servers/[:servername]

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/tutorial/server-api.md.txt

Initiate the launch of a user's server using a POST request. A '201 Created' response means the server is ready immediately, while '202 Accepted' indicates it has started spawning and requires further waiting.

```bash
POST /hub/api/users/:username/servers/[:servername]
```

--------------------------------

### Example of adding a user route

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/howto/proxy.md.txt

This example demonstrates how to add a route for a specific user, including associated user data.

```python
await proxy.add_route('/user/pgeorgiou/', 'http://127.0.0.1:1227',
                {'user': 'pgeorgiou'})
```

--------------------------------

### Start Configurable HTTP Proxy

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/howto/separate-proxy.md.txt

This command starts the configurable-http-proxy. Ensure `--api-ip` and `--api-port` match the hub's `ConfigurableHTTPProxy.api_url`. `--default-target` and `--error-target` should point to the hub.

```bash
$ configurable-http-proxy --ip=127.0.0.1 --port=8000 --api-ip=127.0.0.1 --api-port=8001 --default-target=http://localhost:8081 --error-target=http://localhost:8081/hub/error
```

--------------------------------

### Install Configurable HTTP Proxy Globally

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/contributing/setup.md.txt

Install the configurable-http-proxy globally using npm. This is required for running and testing the default JupyterHub configuration. If permission errors occur, consider using `sudo` or a local install.

```bash
npm install -g configurable-http-proxy
```

--------------------------------

### Install pre-commit hooks

Source: https://jupyterhub.readthedocs.io/en/stable/contributing/tests.html

Install the pre-commit package and register the git hooks to enforce formatting locally.

```bash
pip install pre-commit
pre-commit install --install-hooks
```

--------------------------------

### Example Hub-Managed Service Environment Variables

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/reference/services.md.txt

Shows the specific environment variables passed to the 'idle-culler' service example when it is launched by the Hub.

```bash
JUPYTERHUB_SERVICE_NAME: 'idle-culler'
JUPYTERHUB_API_TOKEN: API token assigned to the service
JUPYTERHUB_API_URL: http://127.0.0.1:8080/hub/api
JUPYTERHUB_BASE_URL: https://mydomain[:port]
JUPYTERHUB_SERVICE_PREFIX: /services/idle-culler/
```

--------------------------------

### Install packages system-wide

Source: https://jupyterhub.readthedocs.io/en/stable/howto/configuration/config-user-env.html

Use this command to install Python packages into the default system environment.

```bash
sudo python3 -m pip install numpy
```

--------------------------------

### Example environment variables for idle-culler

Source: https://jupyterhub.readthedocs.io/en/stable/reference/services.html

Shows the specific environment variables passed to the idle-culler service example.

```text
JUPYTERHUB_SERVICE_NAME: 'idle-culler'
JUPYTERHUB_API_TOKEN: API token assigned to the service
JUPYTERHUB_API_URL: http://127.0.0.1:8080/hub/api
JUPYTERHUB_BASE_URL: https://mydomain[:port]
JUPYTERHUB_SERVICE_PREFIX: /services/idle-culler/
```

--------------------------------

### Build and install SELinux module

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/howto/configuration/config-sudo.md.txt

Compile the SELinux policy definition into a module and install it on the system. This is part of the SELinux troubleshooting steps.

```bash
$ checkmodule -M -m -o sudo_exec_selinux.mod sudo_exec_selinux.te
$ semodule_package -o sudo_exec_selinux.pp -m sudo_exec_selinux.mod
$ semodule -i sudo_exec_selinux.pp
```

--------------------------------

### Install kernelspecs system-wide

Source: https://jupyterhub.readthedocs.io/en/stable/howto/configuration/config-user-env.html

Install kernel specifications to a system-wide prefix to make them accessible to all users on the system.

```bash
/path/to/python3 -m ipykernel install --prefix=/usr/local
/path/to/python2 -m ipykernel install --prefix=/usr/local
```

--------------------------------

### Start JupyterHub for Development

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/contributing/setup.md.txt

Start the JupyterHub service using a development configuration file. This allows you to test your changes locally.

```bash
jupyterhub -f testing/jupyterhub_config.py
```

--------------------------------

### Install Node.js and npm on Linux

Source: https://jupyterhub.readthedocs.io/en/stable/tutorial/quickstart.html

Use the system package manager to install Node.js and npm on Debian/Ubuntu systems.

```bash
sudo apt-get install nodejs npm
```

--------------------------------

### Implementing proxy start and stop methods

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/howto/proxy.md.txt

Define `start` and `stop` methods if the proxy should be launched and managed by the Hub. These methods can be coroutines. `c.Proxy.should_start` controls whether these are called.

```python
class MyProxy(Proxy):
    ... 
    async def start(self):
        """Start the proxy"""

    async def stop(self):
        """Stop the proxy"""
```

--------------------------------

### Install sudospawner

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/howto/configuration/config-sudo.md.txt

Install the `sudospawner` package using pip. This enables JupyterHub to monitor single-user servers via sudo.

```bash
sudo python3 -m pip install sudospawner
```

--------------------------------

### Install Configurable HTTP Proxy with Conda

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/contributing/setup.md.txt

Install configurable-http-proxy using conda if you are working within a conda environment.

```bash
conda install configurable-http-proxy
```

--------------------------------

### Start the JupyterHub server

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/tutorial/quickstart.md.txt

Run this command to start the JupyterHub server. Access it via http://localhost:8000 and sign in with your Unix credentials.

```bash
jupyterhub
```

--------------------------------

### Install and Configure Pre-commit for Local Formatting

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/contributing/tests.md.txt

Install the pre-commit package and register git hooks to automatically format code before committing. This ensures consistent code style across the project.

```bash
pip install pre-commit
pre-commit install --install-hooks
```

--------------------------------

### Install Documentation Build Packages

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/contributing/docs.md.txt

Installs the necessary Python packages for building JupyterHub's documentation, including dependencies from requirements.txt and sphinx-autobuild for live reloading.

```bash
python3 -m pip install -r docs/requirements.txt
python3 -m pip install sphinx-autobuild
```

--------------------------------

### Start a server API request

Source: https://jupyterhub.readthedocs.io/en/stable/tutorial/server-api.html

Endpoint for initiating a server launch.

```http
POST /hub/api/users/:username/servers/[:servername]
```

--------------------------------

### Basic Spawner start method

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/reference/spawners.md.txt

Illustrates a typical implementation of the `Spawner.start` method, including setting IP and port, retrieving environment variables, constructing the command, and initiating the server process.

```python
async def start(self):
    self.ip = '127.0.0.1'
    self.port = random_port()
    # get environment variables,
    # several of which are required for configuring the single-user server
    env = self.get_env()
    cmd = []
    # get jupyterhub command to run,
    # typically ['jupyterhub-singleuser']
    cmd.extend(self.cmd)
    cmd.extend(self.get_args())

    await self._actually_start_server_somehow(cmd, env)
    # url may not match self.ip:self.port, but it could!
    url = self._get_connectable_url()
    return url
```

--------------------------------

### GET /metrics

Source: https://jupyterhub.readthedocs.io/en/stable/reference/monitoring.html

Retrieves the current operational state of the JupyterHub installation in Prometheus-compatible text format.

```APIDOC
## GET /metrics

### Description
Returns the current operational state of the JupyterHub instance. The output is formatted for consumption by Prometheus.

### Method
GET

### Endpoint
/metrics
```

--------------------------------

### Implement Spawner.start method

Source: https://jupyterhub.readthedocs.io/en/stable/reference/spawners.html

Standard implementation of the start method to launch a single-user server and return its connection URL.

```python
async def start(self):
    self.ip = '127.0.0.1'
    self.port = random_port()
    # get environment variables,
    # several of which are required for configuring the single-user server
    env = self.get_env()
    cmd = []
    # get jupyterhub command to run,
    # typically ['jupyterhub-singleuser']
    cmd.extend(self.cmd)
    cmd.extend(self.get_args())

    await self._actually_start_server_somehow(cmd, env)
    # url may not match self.ip:self.port, but it could!
    url = self._get_connectable_url()
    return url
```

--------------------------------

### Implement a pre-spawn hook

Source: https://jupyterhub.readthedocs.io/en/stable/reference/api/spawner.html

Example of a pre-spawn hook function used to modify the spawner environment before the server starts.

```python
def my_hook(spawner):
    username = spawner.user.name
    spawner.environment["GREETING"] = f"Hello {username}"

c.Spawner.pre_spawn_hook = my_hook
```

--------------------------------

### Spawner State Management Example

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/reference/spawners.md.txt

Implement methods to get, load, and clear the state for a Spawner, typically used for persisting information like process IDs between server restarts. This example shows how to manage the PID for single-process spawners.

```python
def get_state(self):
    """get the current state"""
    state = super().get_state()
    if self.pid:
        state['pid'] = self.pid
    return state
```

```python
def load_state(self, state):
    """load state from the database"""
    super().load_state(state)
    if 'pid' in state:
        self.pid = state['pid']
```

```python
def clear_state(self):
    """clear any state (called after shutdown)"""
    super().clear_state()
    self.pid = 0
```

--------------------------------

### Example Spawned Command

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/reference/spawners.md.txt

Illustrates the resulting command-line execution after applying Spawner.cmd and Spawner.args configurations.

```bash
my-singleuser-wrapper --debug --flag
```

--------------------------------

### Retrieve User Model via API with Requests

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/reference/services.md.txt

Make a GET request to the /hub/api/user endpoint with an access token in the Authorization header to retrieve the user model. This example uses the requests library.

```python
r = requests.get(
    "http://127.0.0.1:8081/hub/api/user",
    headers = {
        'Authorization' : f'token {api_token}',
    },
)
r.raise_for_status()
user = r.json()
```

--------------------------------

### Spawner.start Method

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/reference/spawners.md.txt

The `Spawner.start` method is responsible for initiating a single-user server for a given user. It should return the `(ip, port)` of the running server or a full URL. The example demonstrates how to construct the command and environment variables for the server process.

```APIDOC
## Spawner.start

### Description
Starts a single-user server for a single user. Information about the user is available via `self.user`. The return value should be the `(ip, port)` of the running server, or a full URL as a string.

### Method
`async def start(self)`

### Parameters
None explicitly defined, but relies on instance attributes like `self.user`, `self.ip`, `self.port`, `self.cmd`, and methods like `self.get_env()`, `self.get_args()`, `self._get_connectable_url()`.

### Request Example
```python
async def start(self):
    self.ip = '127.0.0.1'
    self.port = random_port()
    # get environment variables, 
    # several of which are required for configuring the single-user server
    env = self.get_env()
    cmd = []
    # get jupyterhub command to run, 
    # typically ['jupyterhub-singleuser']
    cmd.extend(self.cmd)
    cmd.extend(self.get_args())

    await self._actually_start_server_somehow(cmd, env)
    # url may not match self.ip:self.port, but it could!
    url = self._get_connectable_url()
    return url
```

### Response
- **(ip, port)** or **URL** (string) - The connection details for the running server.

### Response Example
`'http://127.0.0.1:8888'`

### Exception Handling
If `Spawner.start` raises an Exception, a message can be passed to the user via `.jupyterhub_html_message` (rendered as HTML) or `.jupyterhub_message` (rendered as plain text).
```

--------------------------------

### Configure Proxy Startup

Source: https://jupyterhub.readthedocs.io/en/stable/reference/config-reference.html

Set the proxy startup behavior in the configuration file.

```python
c.ConfigurableHTTPProxy.should_start = True
```

--------------------------------

### Install JupyterHub with conda

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/tutorial/quickstart.md.txt

Install JupyterHub and its proxy using conda. Also installs JupyterLab and notebook if needed for the same environment.

```bash
conda install -c conda-forge jupyterhub  # installs jupyterhub and proxy
conda install jupyterlab notebook  # needed if running the notebook servers in the same environment
```

--------------------------------

### Install Node.js and npm on Debian/Ubuntu

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/tutorial/quickstart.md.txt

Use this command to install Node.js and npm on Debian/Ubuntu systems if you are using pip for JupyterHub installation.

```bash
sudo apt-get install nodejs npm
```

--------------------------------

### Install JupyterHub with pip and npm

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/tutorial/quickstart.md.txt

Install JupyterHub and the configurable-http-proxy using pip and npm. Also installs JupyterLab and notebook if needed for the same environment.

```bash
python3 -m pip install jupyterhub
npm install -g configurable-http-proxy
python3 -m pip install jupyterlab notebook  # needed if running the notebook servers in the same environment
```

--------------------------------

### Install Python Package System-Wide

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/howto/configuration/config-user-env.md.txt

Use pip to install Python packages system-wide for all users. Ensure the installation location is readable and executable by users.

```bash
sudo python3 -m pip install numpy
```

--------------------------------

### GET /hub/api/services/{name}

Source: https://jupyterhub.readthedocs.io/en/stable/reference/rest-api.html

Get details for a specific service by name.

```APIDOC
## GET /hub/api/services/{name}

### Description
Retrieve the Service model for a specific service.

### Method
GET

### Endpoint
/hub/api/services/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - service name

### Response
#### Success Response (200)
- **service** (object) - The Service model

#### Response Example
{
  "name": "string",
  "kind": "service",
  "admin": true,
  "roles": ["string"],
  "url": "string",
  "prefix": "string",
  "pid": 0,
  "command": ["string"],
  "info": {}
}
```

--------------------------------

### Start a user's notebook server

Source: https://jupyterhub.readthedocs.io/en/stable/reference/rest-api.html

Empty JSON payload used to trigger the spawning of a user's notebook server.

```json
{ }
```

--------------------------------

### Configure PAMAuthenticator user creation command

Source: https://jupyterhub.readthedocs.io/en/stable/reference/config-reference.html

Example of setting a custom home directory command for user creation.

```python
['adduser', '-q', '--gecos', '""', '--home', '/customhome/USERNAME', '--disabled-password']
```

```bash
adduser -q --gecos "" --home /customhome/river --disabled-password river
```

--------------------------------

### Install JavaScript dependencies

Source: https://jupyterhub.readthedocs.io/en/stable/contributing/setup.html

Installs necessary NodeJS dependencies when lessc is missing.

```bash
npm install
```

--------------------------------

### List Installed Kernelspecs

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/howto/configuration/config-user-env.md.txt

Command to list the locations of all installed Jupyter kernelspecs.

```bash
jupyter kernelspec list
```

--------------------------------

### POST /hub/api/users/{name}/server

Source: https://jupyterhub.readthedocs.io/en/stable/reference/rest-api.html

Start a user's single-user notebook server.

```APIDOC
## POST /hub/api/users/{name}/server

### Description
Start a user's single-user notebook server. Spawn options can be passed as a JSON body.

### Method
POST

### Endpoint
/hub/api/users/{name}/server

### Parameters
#### Path Parameters
- **name** (string) - Required - The username of the user.

#### Request Body
- **user_options** (object) - Optional - Spawn options for the Spawner.

### Request Example
{}

### Response
#### Success Response (201)
- The user's notebook server has started

#### Success Response (202)
- The user's notebook server has not yet started, but has been requested
```

--------------------------------

### Create multiple users response sample

Source: https://jupyterhub.readthedocs.io/en/stable/reference/rest-api.html

Example JSON response returned after successfully creating multiple users.

```json
[
  {
    "name": "string",
    "kind": "user",
    "admin": true,
    "roles": [
      "string"
],
    "groups": [
      "string"
],
    "server": "string",
    "pending": "spawn",
    "last_activity": "2019-08-24T14:15:22Z",
    "servers": {
      "property1": {
        "name": "string",
        "ready": true,
        "stopped": true,
        "pending": "spawn",
        "url": "string",
        "progress_url": "string",
        "full_url": "string",
        "full_progress_url": "string",
        "started": "2019-08-24T14:15:22Z",
        "last_activity": "2019-08-24T14:15:22Z",
        "state": { },
        "user_options": { }
},
      "property2": {
        "name": "string",
        "ready": true,
        "stopped": true,
        "pending": "spawn",
        "url": "string",
        "progress_url": "string",
        "full_url": "string",
        "full_progress_url": "string",
        "started": "2019-08-24T14:15:22Z",
        "last_activity": "2019-08-24T14:15:22Z",
        "state": { },
        "user_options": { }
}
},
    "auth_state": { }
}

]
```

--------------------------------

### Compile and install SELinux module

Source: https://jupyterhub.readthedocs.io/en/stable/howto/configuration/config-sudo.html

Execute these commands as root to compile and load the SELinux policy module.

```bash
$ checkmodule -M -m -o sudo_exec_selinux.mod sudo_exec_selinux.te
$ semodule_package -o sudo_exec_selinux.pp -m sudo_exec_selinux.mod
$ semodule -i sudo_exec_selinux.pp
```

--------------------------------

### Install idle-culler package

Source: https://jupyterhub.readthedocs.io/en/stable/tutorial/getting-started/services-basics.html

Install the idle-culler package via pip to enable server culling functionality.

```bash
pip install jupyterhub-idle-culler
```

--------------------------------

### Ready server progress event

Source: https://jupyterhub.readthedocs.io/en/stable/tutorial/server-api.html

Example of a progress event when the server is fully ready.

```json
{
  "progress": 100,
  "ready": true,
  "message": "Server ready at /user/test-1/",
  "html_message": "Server ready at <a href=\"/user/test-1/\">/user/test-1/</a>",
  "url": "/user/test-1/"
}
```

--------------------------------

### Define proxy startup command

Source: https://jupyterhub.readthedocs.io/en/stable/reference/config-reference.html

Specifies the command used to launch the proxy process.

```python
# c.ConfigurableHTTPProxy.command = ['configurable-http-proxy']
```

--------------------------------

### Install JupyterHub Dependencies Offline

Source: https://jupyterhub.readthedocs.io/en/stable/faq/troubleshooting.html

Create local wheels or packages for installation without an internet connection.

```bash
python3 -m pip wheel jupyterhub
npmbox configurable-http-proxy
```

--------------------------------

### Registering an Authenticator via entry points

Source: https://jupyterhub.readthedocs.io/en/stable/reference/authenticators.html

Add this entry point configuration to your package's setup.py to allow admins to reference your authenticator by a short name.

```python
setup(
  ...
  entry_points={
    'jupyterhub.authenticators': [
        'myservice = mypackage:MyAuthenticator',
    ],
  },
)
```

--------------------------------

### Example Route Structure

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/howto/proxy.md.txt

Illustrates the expected dictionary format for routes, including routespec, target, and data.

```json
{
  '/proxy/path/': {
    'routespec': '/proxy/path/',
    'target': 'http://...',
    'data': {},
  },
}
```

--------------------------------

### Define LocalProcessSpawner Options Form

Source: https://jupyterhub.readthedocs.io/en/stable/reference/api/spawner.html

Provides an HTML snippet for user-specified launch options.

```html
Set your key:
<input name="key" val="default_key"></input>
<br>
Choose a letter:
<select name="letter" multiple="true">
  <option value="A">The letter A</option>
  <option value="B">The letter B</option>
</select>
```

```python
c.LocalProcessSpawner.options_form = Union()
```

--------------------------------

### Test JupyterHub and proxy installation

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/tutorial/quickstart.md.txt

Verify that JupyterHub and configurable-http-proxy are installed correctly by checking their help messages.

```bash
jupyterhub -h
configurable-http-proxy -h
```

--------------------------------

### GET /api/users/:username/shared/:ownername/:servername

Source: https://jupyterhub.readthedocs.io/en/stable/reference/sharing.html

Get permission info for a single user on a single server.

```APIDOC
## GET /api/users/:username/shared/:ownername/:servername

### Description
Returns the Share information for a specific user on a specific server.

### Method
GET

### Endpoint
/api/users/:username/shared/:ownername/:servername
```

--------------------------------

### Start JupyterHub for testing

Source: https://jupyterhub.readthedocs.io/en/stable/contributing/setup.html

Launch the JupyterHub process using the testing configuration file.

```bash
jupyterhub -f testing/jupyterhub_config.py
```

--------------------------------

### Build and Serve Documentation Locally

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/contributing/docs.md.txt

Builds the HTML version of the documentation using sphinx-autobuild and serves it locally for live preview. This command automatically rebuilds the documentation upon detecting changes.

```bash
sphinx-autobuild docs/source/ docs/_build/html
```

--------------------------------

### Configure Spawner start timeout

Source: https://jupyterhub.readthedocs.io/en/stable/reference/config-reference.html

Sets the maximum time in seconds to wait for the server process to start.

```python
c.Spawner.start_timeout = 60
```

--------------------------------

### Configure custom components via entry points

Source: https://jupyterhub.readthedocs.io/en/stable/reference/changelog.html

Use entry points to specify custom authenticator, spawner, and proxy classes in the configuration.

```python
c.JupyterHub.authenticator_class = 'github'
c.JupyterHub.spawner_class = 'docker'
c.JupyterHub.proxy_class = 'traefik_etcd'
```

--------------------------------

### Install JupyterHub via conda

Source: https://jupyterhub.readthedocs.io/en/stable/tutorial/quickstart.html

Install JupyterHub, the proxy, and notebook server dependencies using the conda-forge channel.

```bash
conda install -c conda-forge jupyterhub  # installs jupyterhub and proxy
conda install jupyterlab notebook  # needed if running the notebook servers in the same environment
```

--------------------------------

### Launch default server via API

Source: https://jupyterhub.readthedocs.io/en/stable/howto/rest.html

The legacy method for launching a single default server for a user.

```bash
curl -X POST -H "Authorization: token <token>" "http://127.0.0.1:8081/hub/api/users/<user>/server"
```

--------------------------------

### Configure shadow group and permissions (FreeBSD)

Source: https://jupyterhub.readthedocs.io/en/stable/_sources/howto/configuration/config-sudo.md.txt

Create a 'shadow' group, assign ownership of /etc/spwd.db and /etc/master.passwd to it, and grant group read permissions on FreeBSD.

```bash
$ sudo pw group add shadow
$ sudo chgrp shadow /etc/spwd.db
$ sudo chmod g+r /etc/spwd.db
$ sudo chgrp shadow /etc/master.passwd
$ sudo chmod g+r /etc/master.passwd
```

--------------------------------

### Define server launch options form

Source: https://jupyterhub.readthedocs.io/en/stable/reference/api/spawner.html

Provides an HTML snippet for user-specified launch options. Data is passed to the spawner via self.user_options.

```html
Set your key:
<input name="key" val="default_key"></input>
<br>
Choose a letter:
<select name="letter" multiple="true">
  <option value="A">The letter A</option>
  <option value="B">The letter B</option>
</select>
```

--------------------------------

### Get User by Name Response Structure

Source: https://jupyterhub.readthedocs.io/en/stable/reference/rest-api.html

Represents the JSON schema returned by the GET /hub/api/users/{name} endpoint.

```json
{
  * "name": "string",
  * "kind": "user",
  * "admin": true,
  * "roles": [
    * "string"
],
  * "groups": [
    * "string"
],
  * "server": "string",
  * "pending": "spawn",
  * "last_activity": "2019-08-24T14:15:22Z",
  * "servers": {
    * "property1": {
      * "name": "string",
      * "ready": true,
      * "stopped": true,
      * "pending": "spawn",
      * "url": "string",
      * "progress_url": "string",
      * "full_url": "string",
      * "full_progress_url": "string",
      * "started": "2019-08-24T14:15:22Z",
      * "last_activity": "2019-08-24T14:15:22Z",
      * "state": { },
      * "user_options": { }
},
    * "property2": {
      * "name": "string",
      * "ready": true,
      * "stopped": true,
      * "pending": "spawn",
      * "url": "string",
      * "progress_url": "string",
      * "full_url": "string",
      * "full_progress_url": "string",
      * "started": "2019-08-24T14:15:22Z",
      * "last_activity": "2019-08-24T14:15:22Z",
      * "state": { },
      * "user_options": { }
}
},
  * "auth_state": { }

}
```

--------------------------------

### Enable Apache modules

Source: https://jupyterhub.readthedocs.io/en/stable/howto/configuration/config-proxy.html

Required modules for proxying, SSL, and WebSocket support.

```bash
a2enmod ssl rewrite proxy headers proxy_http proxy_wstunnel
```
Tokens:
Raw