mirror of
https://github.com/jupyterhub/the-littlest-jupyterhub.git
synced 2025-12-18 21:54:05 +08:00
133 lines
4.9 KiB
Markdown
133 lines
4.9 KiB
Markdown
(contributing-plugins)=
|
|
|
|
# TLJH Plugins
|
|
|
|
TLJH plugins are the official way to make customized 'spins' or 'stacks'
|
|
with TLJH as the base. For example, the earth sciences community can make
|
|
a plugin that installs commonly used packages, set up authentication
|
|
and pre-download useful datasets. The mybinder.org community can
|
|
make a plugin that gives you a single-node, single-repository mybinder.org.
|
|
Plugins are very powerful, so the possibilities are endless.
|
|
|
|
## Design
|
|
|
|
[pluggy](https://github.com/pytest-dev/pluggy) is used to implement
|
|
plugin functionality. TLJH exposes specific **hooks** that your plugin
|
|
can provide implementations for. This allows us to have specific hook
|
|
points in the application that can be explicitly extended by plugins,
|
|
balancing the need to change TLJH internals in the future with the
|
|
stability required for a good plugin ecosystem.
|
|
|
|
## Installing Plugins
|
|
|
|
Include `--plugin <install_name>` in the Installer script. See [](/topic/customizing-installer) for more info.
|
|
|
|
## Writing a simple plugins
|
|
|
|
We shall try to write a simple plugin that installs a few libraries,
|
|
and use it to explain how the plugin mechanism works. We shall call
|
|
this plugin `tljh-simple`.
|
|
|
|
### Plugin directory layout
|
|
|
|
We recommend creating a new git repo for your plugin. Plugins are
|
|
normal python packages - however, since they are usually simpler,
|
|
we recommend they live in one file.
|
|
|
|
For `tljh-simple`, the repository's structure should look like:
|
|
|
|
```none
|
|
tljh_simple:
|
|
- tljh_simple.py
|
|
- setup.py
|
|
- README.md
|
|
- LICENSE
|
|
```
|
|
|
|
The `README.md` (or `README.rst` file) contains human readable
|
|
information about what your plugin does for your users. `LICENSE`
|
|
specifies the license used by your plugin - we recommend the
|
|
3-Clause BSD License, since that is what is used by TLJH itself.
|
|
|
|
### `setup.py` - metadata & registration
|
|
|
|
`setup.py` marks this as a python package, and contains metadata
|
|
about the package itself. It should look something like:
|
|
|
|
```python
|
|
from setuptools import setup
|
|
|
|
setup(
|
|
name="tljh-simple",
|
|
author="YuviPanda",
|
|
version="0.1",
|
|
license="3-clause BSD",
|
|
url='https://github.com/yuvipanda/tljh-simple',
|
|
entry_points={"tljh": ["simple = tljh_simple"]},
|
|
py_modules=["tljh_simple"],
|
|
)
|
|
```
|
|
|
|
This is a mostly standard `setup.py` file. `entry_points={"tljh": ["simple = tljh_simple]}`
|
|
'registers' the module `tljh_simple` (in file `tljh_simple.py`) with TLJH as a plugin.
|
|
|
|
### `tljh_simple.py` - implementation
|
|
|
|
In `tljh_simple.py`, you provide implementations for whichever hooks
|
|
you want to extend.
|
|
|
|
A hook implementation is a function that has the following characteristics:
|
|
|
|
1. Has same name as the hook
|
|
2. Accepts some or all of the parameters defined for the hook
|
|
3. Is decorated with the `hookimpl` decorator function, imported from
|
|
`tljh.hooks`.
|
|
|
|
The current list of available hooks and when they are called can be
|
|
seen in [tljh/hooks.py](https://github.com/jupyterhub/the-littlest-jupyterhub/blob/main/tljh/hooks.py)
|
|
in the source repository. Example implementations of each hook can be referenced from
|
|
[integration-tests/plugins/simplest/tljh_simplest.py](https://github.com/jupyterhub/the-littlest-jupyterhub/blob/main/integration-tests/plugins/simplest/tljh_simplest.py).
|
|
|
|
This example provides an implementation for the `tljh_extra_user_conda_packages`
|
|
hook, which can return a list of conda packages that'll be installed in users'
|
|
environment from conda-forge.
|
|
|
|
```python
|
|
from tljh.hooks import hookimpl
|
|
|
|
@hookimpl
|
|
def tljh_extra_user_conda_packages():
|
|
return [
|
|
'xarray',
|
|
'iris',
|
|
'dask',
|
|
]
|
|
```
|
|
|
|
## Publishing plugins
|
|
|
|
Plugins are python packages and should be published on PyPI. Users
|
|
can also install them directly from GitHub - although this is
|
|
not good long term practice.
|
|
|
|
The python package should be named `tljh-<pluginname>`.
|
|
|
|
## List of known plugins
|
|
|
|
If you are looking for a way to extend or customize your TLJH deployment, you might want to look for existing plugins.
|
|
|
|
Here is a non-exhaustive list of known TLJH plugins:
|
|
|
|
- [tljh-pangeo](https://github.com/yuvipanda/tljh-pangeo): TLJH plugin for setting up the Pangeo Stack.
|
|
- [tljh-voila-gallery](https://github.com/voila-dashboards/tljh-voila-gallery): TLJH plugin that installs a gallery of Voilà dashboards.
|
|
- [tljh-repo2docker](https://github.com/plasmabio/tljh-repo2docker): TLJH plugin to build multiple user environments with
|
|
[repo2docker](https://repo2docker.readthedocs.io).
|
|
- [tljh-shared-directory](https://github.com/kafonek/tljh-shared-directory): TLJH plugin which sets up a _shared directory_
|
|
for the Hub users in `/srv/scratch`.
|
|
- [tljh-db](https://github.com/sinzlab/tljh-db): TLJH plugin for working with mysql databases.
|
|
|
|
If you have authored a plugin, please open a PR to add it to this list!
|
|
|
|
We also recommend adding the `tljh-plugin` topic to the GitHub repository to make it more discoverable:
|
|
[https://github.com/topics/tljh-plugin](https://github.com/topics/tljh-plugin)
|