Moved last set of Tutorials

2025-10-13 21:13:01 +00:00 · 2023-02-03 15:57:35 +03:00
parent 63f164ca53
commit f857b17022
13 changed files with 44 additions and 37 deletions
--- a/docs/source/tutorial/getting-started/services-basics.md
+++ b/docs/source/tutorial/getting-started/services-basics.md
@@ -0,0 +1,149 @@
+# External 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 specific
+action or task. For example, shutting down individuals' single user
+notebook servers that have been idle for some time is a good example of
+a task that could be automated by a Service. Let's look at how the
+[jupyterhub_idle_culler][] script can be used as a Service.
+
+## Real-world example to cull idle servers
+
+JupyterHub has a REST API that can be used by external services. This
+document will:
+
+- explain some basic information about API tokens
+- clarify that API tokens can be used to authenticate to
+  single-user servers as of [version 0.8.0](changelog)
+- show how the [jupyterhub_idle_culler][] script can be:
+  - used in a Hub-managed service
+  - run as a standalone script
+
+Both examples for `jupyterhub_idle_culler` will communicate tasks to the
+Hub via the REST API.
+
+## API Token basics
+
+### Step 1: Generate an API token
+
+To run such an external service, an API token must be created and
+provided to the service.
+
+As of [version 0.6.0](changelog), the preferred way of doing
+this is to first generate an API token:
+
+```bash
+openssl rand -hex 32
+```
+
+In [version 0.8.0](changelog), a TOKEN request page for
+generating an API token is available from the JupyterHub user interface:
+
+![Request API TOKEN page](/images/token-request.png)
+
+![API TOKEN success page](/images/token-request-success.png)
+
+### Step 2: Pass environment variable with token to the Hub
+
+In the case of `cull_idle_servers`, it is passed as the environment
+variable called `JUPYTERHUB_API_TOKEN`.
+
+### Step 3: Use API tokens for services and tasks that require external access
+
+While API tokens are often associated with a specific user, API tokens
+can be used by services that require external access for activities
+that may not correspond to a specific human, e.g. adding users during
+setup for a tutorial or workshop. Add a service and its API token to the
+JupyterHub configuration file, `jupyterhub_config.py`:
+
+```python
+c.JupyterHub.services = [
+    {'name': 'adding-users', 'api_token': 'super-secret-token'},
+]
+```
+
+### Step 4: Restart JupyterHub
+
+Upon restarting JupyterHub, you should see a message like below in the
+logs:
+
+```none
+Adding API token for <username>
+```
+
+## Authenticating to single-user servers using API token
+
+In JupyterHub 0.7, there is no mechanism for token authentication to
+single-user servers, and only cookies can be used for authentication.
+0.8 supports using JupyterHub API tokens to authenticate to single-user
+servers.
+
+## How to configure the idle culler to run as a Hub-Managed Service
+
+### Step 1: Install the idle culler:
+
+```
+pip install jupyterhub-idle-culler
+```
+
+### Step 2: In `jupyterhub_config.py`, add the following dictionary for the `idle-culler` Service to the `c.JupyterHub.services` list:
+
+```python
+c.JupyterHub.services = [
+    {
+        'name': 'idle-culler',
+        'command': [sys.executable, '-m', 'jupyterhub_idle_culler', '--timeout=3600'],
+    }
+]
+
+c.JupyterHub.load_roles = [
+    {
+        "name": "list-and-cull", # name the role
+        "services": [
+            "idle-culler", # assign the service to this role
+        ],
+        "scopes": [
+            # declare what permissions the service should have
+            "list:users", # list users
+            "read:users:activity", # read user last-activity
+            "admin:servers", # start/stop servers
+        ],
+    }
+]
+```
+
+where:
+
+- `command` indicates that the Service will be launched as a
+  subprocess, managed by the Hub.
+
+```{versionchanged} 2.0
+Prior to 2.0, the idle-culler required 'admin' permissions.
+It now needs the scopes:
+
+- `list:users` to access the user list endpoint
+- `read:users:activity` to read activity info
+- `admin:servers` to start/stop servers
+```
+
+## How to run `cull-idle` manually as a standalone script
+
+Now you can run your script by providing it
+the API token and it will authenticate through the REST API to
+interact with it.
+
+This will run the idle culler service manually. It can be run as a standalone
+script anywhere with access to the Hub, and will periodically check for idle
+servers and shut them down via the Hub's REST API. In order to shutdown the
+servers, the token given to `cull-idle` must have permission to list users
+and admin their servers.
+
+Generate an API token and store it in the `JUPYTERHUB_API_TOKEN` environment
+variable. Run `jupyterhub_idle_culler` manually.
+
+```bash
+    export JUPYTERHUB_API_TOKEN='token'
+    python -m jupyterhub_idle_culler [--timeout=900] [--url=http://127.0.0.1:8081/hub/api]
+```
+
+[jupyterhub_idle_culler]: https://github.com/jupyterhub/jupyterhub-idle-culler