feat: plugin documentation

documentation/docs/03-rsd-instance/05-plugins.md

@@ -0,0 +1,67 @@
+# Plugins
+
+:::info
+Plugin support is currently under development and in testing phase, the API may be subject to changes.
+:::
+
+The RSD provides limited support for plugins, enabling third-party services to insert links into dedicated areas (plugin slots) within the user interface.
+
+Plugins can be configured so that they can run in the same docker network, or on different servers.
+
+## Configuration
+
+### Environment Variables
+
+If you are deploying the plugins alongside the main RSD in the same Docker network, the frontend container needs access to the environment variable `RSD_REVERSE_PROXY_URL`.
+By default, the variable is set to:
+
+```shell
+RSD_REVERSE_PROXY_URL=http://nginx
+```
+
+### Frontend settings
+
+For the RSD frontend to know which plugins should be used, they are configure in the `host` property of `frontend/public/data/settings.json`:
+
+```json
+{
+  "host": {
+    "plugins": ["<plugin>"]
+  }
+}
+```
+
+Options for `<plugin>`:
+
+* **url**: starting with `http://`or `https://` pointing to the root url of the plugin without `/api`
+* **slug**: will be used when querying the plugin settings via `/plugin/<plugin>/api/v1/config` inside the servers own docker network
+
+## nginx configuration
+
+If the plugin is running in the same Docker network, `plugin` must be added to `nginx.conf` as a new location in the main server block:
+
+```nginx
+server {
+	listen       80 default_server;
+	server_name  localhost;
+
+	# ...
+
+	# The root path of the plugin API	
+	location /plugin/plugin/api/ {
+		resolver 127.0.0.11 valid=30s ipv6=off;
+		set $pluginbackend <PluginBackendContainer>;
+
+		proxy_set_header Host $host;
+		proxy_set_header X-Real-IP $remote_addr;
+		default_type application/json;
+		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 `<PluginBackendContainer>` by the respective container name, and port if necessary, where the backend is accessible.
+This information should be provided in the documentation of the plugin.

documentation/docs/03-rsd-instance/05-plugins.md.license

@@ -0,0 +1,5 @@
+SPDX-FileCopyrightText: 2024 Christian Meeßen (GFZ) <christian.meessen@gfz-potsdam.de>
+SPDX-FileCopyrightText: 2024 Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences
+
+SPDX-License-Identifier: CC-BY-4.0
+

documentation/docs/04-contribute/06-plugin-development.md

@@ -0,0 +1,54 @@
+<!--
+SPDX-FileCopyrightText: 2024 Christian Meeßen (GFZ) <christian.meessen@gfz-potsdam.de>
+SPDX-FileCopyrightText: 2024 Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+# Plugin Development
+
+:::info
+Plugin support is currently under development and in testing phase, the API may be subject to changes.
+:::
+
+The RSD provides limited support for plugins, enabling third-party services to insert links into dedicated areas (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) Next.js performs GET requests to all registered plugins, to the endpoints `<baseUrl>/plugin/<plugin>/api/v1/config`. The `baseUrl` is determined by the plugin name in `settings.json`. If a user is signed it, the 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.
+2) If necessary, the plugin backend verifies the user token.
+3) The plugin backend returns a list of `PluginSlot` that need to be in the following format:
+   ```typescript
+   type PluginSlot={
+     slot: PluginSlot,
+     icon: string,
+     href: string,
+     title: string,
+     subtitle: string | null
+   }
+   ```
+   where `PluginSlotNames` is:
+   ```typescript
+   type PluginSlot = 'userMenu' | 'editSoftwareNav'
+   ```
+4) The plugin slots are stored in the global `<RsdPluginContext>` 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.

documentation/docs/04-contribute/img/softwareNavPlugin.png.license

@@ -0,0 +1,4 @@
+SPDX-FileCopyrightText: 2024 Christian Meeßen (GFZ) <christian.meessen@gfz-potsdam.de>
+SPDX-FileCopyrightText: 2024 Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences
+
+SPDX-License-Identifier: CC-BY-4.0

documentation/docs/04-contribute/img/userMenuPlugin.png.license

@@ -0,0 +1,4 @@
+SPDX-FileCopyrightText: 2024 Christian Meeßen (GFZ) <christian.meessen@gfz-potsdam.de>
+SPDX-FileCopyrightText: 2024 Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences
+
+SPDX-License-Identifier: CC-BY-4.0