Debian Codegraph @

examples/service-announcement/README.md

raw
1 # Simple Announcement Service Example
2
3 This is a simple service that allows administrators to manage announcements
4 that appear when JupyterHub renders pages.
5
6 To run the service as a hub-managed service simply include in your JupyterHub
7 configuration file something like:
8
9 :notebook:**Info**: You can run the announcement service example from the `examples`
10 directory, using one of the several services provided by JupyterHub.
11
12 ```python
13
14 import sys
15
16 from pathlib import Path
17 # absolute path to announcement.py
18 announcement_py = str(Path(__file__).parent.joinpath("announcement.py").resolve())
19
20 #ensure get_config() is added in
21 c = get_config()
22
23 ...
24 ..
25
26 c.JupyterHub.services = [
27 {
28 'name': 'announcement',
29 'url': 'http://127.0.0.1:8888',
30 'command': [sys.executable, announcement_py, "--port", "8888"],
31 }
32 ]
33 ```
34
35 This starts the announcements service up at `/services/announcement/` when
36 JupyterHub launches. By default the announcement text is empty.
37
38 The `announcement` module has a configurable port (default 8888) and an API
39 prefix setting. By default the API prefix is `JUPYTERHUB_SERVICE_PREFIX` if
40 that environment variable is set or `/` if it is not.
41
42 ## Managing the Announcement
43
44 Users with permission can set the announcement text with an API token:
45
46 $ curl -X POST -H "Authorization: token <token>" \
47 -d '{"announcement":"JupyterHub will be upgraded on August 14!"}' \
48 https://.../services/announcement/
49
50 To grant permission, add a role (JupyterHub 2.0) with access to the announcement service:
51
52 ```python
53 # grant the 'announcer' permission to access the announcement service
54 c.JupyterHub.load_roles = [
55 {
56 "name": "announcers",
57 "users": ["announcer"], # or groups
58 "scopes": ["access:services!service=announcement"],
59 }
60 ]
61 ```
62
63 Anyone can read the announcement:
64
65 $ curl https://.../services/announcement/ | python -m json.tool
66 {
67 announcement: "JupyterHub will be upgraded on August 14!",
68 timestamp: "...",
69 user: "..."
70 }
71
72 The time the announcement was posted is recorded in the `timestamp` field and
73 the user who posted the announcement is recorded in the `user` field.
74
75 To clear the announcement text, send a DELETE request.
76 This has the same permission requirement.
77
78 $ curl -X DELETE -H "Authorization: token <token>" \
79 https://.../services/announcement/
80
81 ## Seeing the Announcement in JupyterHub
82
83 To be able to render the announcement, include the provide `page.html` template
84 that extends the base `page.html` template. Set `c.JupyterHub.template_paths`
85 in JupyterHub's configuration to include the path to the extending template.
86 The template changes the `announcement` element and does a JQuery `$.get()` call
87 to retrieve the announcement text.
88
89 JupyterHub's configurable announcement template variables can be set for various
90 pages like login, logout, spawn, and home. Including the template provided in
91 this example overrides all of those.