feat: plugin documentation

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

@@ -0,0 +1,43 @@
+<!--
+SPDX-FileCopyrightText: 2024 Christian Meeßen (GFZ) <[email protected]>
+SPDX-FileCopyrightText: 2024 Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+# 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 <PluginBackendContainer>;
+		proxy_pass http://$pluginbackend:<Port>;
+	}
+}
+```
+:::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>` and `<Port>` by the respective container name and port where the backend is accessible. This is provided in the documentaiton of the plugin.

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

@@ -0,0 +1,54 @@
+<!--
+SPDX-FileCopyrightText: 2024 Christian Meeßen (GFZ) <[email protected]>
+SPDX-FileCopyrightText: 2024 Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+# 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/<plugin>/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 `<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. It must be available via `/modules/<plugin>` where 

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

@@ -0,0 +1,4 @@
+SPDX-FileCopyrightText: 2024 Christian Meeßen (GFZ) <[email protected]>
+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) <[email protected]>
+SPDX-FileCopyrightText: 2024 Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences
+
+SPDX-License-Identifier: CC-BY-4.0