diff --git a/documentation/docs/03-rsd-instance/05-plugins.md b/documentation/docs/03-rsd-instance/05-plugins.md new file mode 100644 index 000000000..ed820df77 --- /dev/null +++ b/documentation/docs/03-rsd-instance/05-plugins.md @@ -0,0 +1,43 @@ + + +# Configuring Plugins + +The RSD offers limited support for plugins, meaning that third party services can add provide links in dedicated slots (plugin slots) within the user interface. + +Plugins need to be integrated into the Docker environment so that they can be executed on the same server. + +## RSD frontend configuration + +For the frontend to know which plugins should be used, add them to the `settings.json` inside the `host` property: + +```json +{ + "host": { + "plugins": ["pluginName"] + } +} +``` + +## nginx configuration + +Add the `pluginName` to `nginx.conf` as a new location: + +```nginx +server { + location /modules/pluginName/ { + resolver 127.0.0.11 valid=30s ipv6=off; + set $pluginbackend ; + proxy_pass http://$pluginbackend:; + } +} +``` +:::tip +Using this configuration, nginx will not exit upon starting if the plugin backend is not reachable yet. 127.0.0.11 is the docker internal resolver. +::: + +Replace `` and `` by the respective container name and port where the backend is accessible. This is provided in the documentaiton of the plugin. diff --git a/documentation/docs/04-contribute/06-plugin-development.md b/documentation/docs/04-contribute/06-plugin-development.md new file mode 100644 index 000000000..b43e414da --- /dev/null +++ b/documentation/docs/04-contribute/06-plugin-development.md @@ -0,0 +1,54 @@ + + +# Plugin Development + +The RSD offers limited support for plugins, meaning that third party services can add provide links in dedicated slots (plugin slots) within the user interface. + +A simple example is available in [research-software-directory/RSD-plugin-example](https://github.com/research-software-directory/RSD-plugin-example). + +## Available plugin slots + +Plugin slots are currently available in the user menu: + +![Plugin slot in the user menu](img/userMenuPlugin.png) + +and at the bottom of the software edit navbar: + +![Plugin slot in the software edit navigation sidebar](img/softwareNavPlugin.png) + +## How plugins work + +1) User needs logs in. +2) NextJS performs GET requests to all registered plugins, to the endpoint `http://localhost/modules//config`. The user token is sent in the header for authentication. The token contains a `data` attribute which can be used to determine which links should be displayed for each user. Users logged in via HelmholtzID have their [`eduPersonEntitlements`](https://hifis.net/doc/helmholtz-aai/attributes/#group-membership-information) delivered within the `data` attribute. +3) If necessary, the plugin backend verifies the user token. +4) The plugin backend returns a list of `PluginSlots` that need to be in the follwoing format: + ```typescript + type PluginSlot={ + name: PluginSlotNames, + icon: string, + href: string, + title: string, + subtitle: string | null + } + ``` + where `PluginSlotNames` is: + ```typescript + enum PluginSlotNames { + userMenu = 'userMenu', + editSoftwareNav = 'editSoftwareNav', + } + ``` +5) The plugin slots are stored in the global `` within the next app and can be accessed by the components. + +## Developing plugins + +If the plugin requires a database, it can either use a new scheme in the existing database container, or provide its own. + +If the plugin provides its own database and user authentication is required, the plugin backend needs access to the `PGRST_JWT_SECRET` so that it can verify the user token. + +The backend of the plugin needs to be added to the reverse proxy configuration. It must be available via `/modules/` where diff --git a/documentation/docs/04-contribute/img/softwareNavPlugin.png b/documentation/docs/04-contribute/img/softwareNavPlugin.png new file mode 100644 index 000000000..1bf3c7cdd Binary files /dev/null and b/documentation/docs/04-contribute/img/softwareNavPlugin.png differ diff --git a/documentation/docs/04-contribute/img/softwareNavPlugin.png.license b/documentation/docs/04-contribute/img/softwareNavPlugin.png.license new file mode 100644 index 000000000..cad968c5e --- /dev/null +++ b/documentation/docs/04-contribute/img/softwareNavPlugin.png.license @@ -0,0 +1,4 @@ +SPDX-FileCopyrightText: 2024 Christian Meeßen (GFZ) +SPDX-FileCopyrightText: 2024 Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences + +SPDX-License-Identifier: CC-BY-4.0 diff --git a/documentation/docs/04-contribute/img/userMenuPlugin.png b/documentation/docs/04-contribute/img/userMenuPlugin.png new file mode 100644 index 000000000..135254d62 Binary files /dev/null and b/documentation/docs/04-contribute/img/userMenuPlugin.png differ diff --git a/documentation/docs/04-contribute/img/userMenuPlugin.png.license b/documentation/docs/04-contribute/img/userMenuPlugin.png.license new file mode 100644 index 000000000..cad968c5e --- /dev/null +++ b/documentation/docs/04-contribute/img/userMenuPlugin.png.license @@ -0,0 +1,4 @@ +SPDX-FileCopyrightText: 2024 Christian Meeßen (GFZ) +SPDX-FileCopyrightText: 2024 Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences + +SPDX-License-Identifier: CC-BY-4.0