docs: add remote RSD section to rsd instance documentation

docs: upgrade docusaurus to v3.6 and use rspack to speedup compilation deployment: update docker-compose.yml file of deployment to include RSD_REMOTE_NAME env variable
research-software-directory · Dec 13, 2024 · 6dc2778 · 6dc2778
1 parent 31a253e
commit 6dc2778
Show file tree

Hide file tree

Showing 10 changed files with 6,390 additions and 3,220 deletions.
diff --git a/deployment/docker-compose.yml b/deployment/docker-compose.yml
@@ -5,7 +5,7 @@
 # SPDX-FileCopyrightText: 2022 Dusan Mijatovic (dv4all)
 # SPDX-FileCopyrightText: 2022 Helmholtz Centre for Environmental Research (UFZ)
 # SPDX-FileCopyrightText: 2022 dv4all
-# SPDX-FileCopyrightText: 2023 Dusan Mijatovic (Netherlands eScience Center)
+# SPDX-FileCopyrightText: 2023 - 2024 Dusan Mijatovic (Netherlands eScience Center)
 #
 # SPDX-License-Identifier: Apache-2.0
 
@@ -24,6 +24,9 @@ services:
       - POSTGRES_USER
       - POSTGRES_PASSWORD
       - POSTGRES_AUTHENTICATOR_PASSWORD
+      - RSD_REMOTE_NAME
+    # insert remote_name into postgres settings, this value is used in initial SQL scripts
+    command: postgres -D /var/lib/postgresql/data -c 'rsd.remote_name=${RSD_REMOTE_NAME}'
     volumes:
       # persist data in named docker volume
       # to remove use: docker compose down --volumes

diff --git a/documentation/babel.config.js b/documentation/babel.config.js
diff --git a/documentation/docs/01-users/05-adding-software.md b/documentation/docs/01-users/05-adding-software.md
@@ -12,7 +12,7 @@ To create a new software page provide a name and a short description (optional)
 
 ## Description
 
-In this section, you can provide the basic information about the software, like a **description** of the software, which will be shown on the software page. You can use [custom Markdown](#custom-markdown) to write the description or [link to existing Markdown](#document-url) page on the web.
+In this section, you can provide the basic information about the software, like a **description** of the software, which will be shown on the software page. You can use [custom Markdown](#custom-markdown) to write the description or [link to existing Markdown](#markdown-url) page on the web.
 
 ### Custom Markdown
 

diff --git a/documentation/docs/03-rsd-instance/01-getting-started.md b/documentation/docs/03-rsd-instance/01-getting-started.md
@@ -22,6 +22,15 @@ POSTGRES_AUTHENTICATOR_PASSWORD=reallyreallyreallyreallyverysafe
 PGRST_JWT_SECRET=reallyreallyreallyreallyverysafe
 ```
 
+- Define remote name of your instance in the .env file. Other RSD instances can pull software information from your instance. How to link the remote RSD instances is described in the [remotes chapter](/rsd-instance/administration/#remotes) of the administration section.
+
+```env
+# RSD REMOTE NAME
+# identify this instance as remote by this name
+# it is used as source label in RPC aggregated_software_overview
+RSD_REMOTE_NAME=Local RSD
+```
+
 - Start RSD using docker compose
 
 ```bash

diff --git a/documentation/docs/03-rsd-instance/03-administration.md b/documentation/docs/03-rsd-instance/03-administration.md
@@ -71,7 +71,8 @@ This section shows all RSD users who logged in to RSD at least once. You can sea
 
 - Removing account will remove all its maintainer roles.
 - You cannot delete account you are currently using.
-  :::
+
+:::
 
 ![animation](img/admin-rsd-users.gif)
 
@@ -193,6 +194,20 @@ In this section, admins can search for mentions and edit them. If you enter a DO
 Edit mentions with care: they might be referenced to in multiple places. If you want to fully change a mention attached to e.g. a software page, you should delete it there and create a new one instead of editing it.
 :::
 
+## Remotes
+
+Here you can define the remote RSD instances that will be used to "enrich" your RSD instance with additional software entries. For each remote you need to provide URL to the homepage of valid RSD instance. If the RSD remote is of version 3 or higher the instance will return instance name suggested by the instance owner. For the earlier RSD versions you need to provide remote name/label manually.
+
+:::tip
+It is advised to use suggested remote name in order to maintain "unanimity" of instance names across the RSD network.
+:::
+
+![animation](img/admin-remotes.gif)
+
+:::info
+When using remote RSD instances each software card in the software overview shows the RSD source. The software from the "local" RSD uses `remote_name` from the rsd_info table. This value is inserted in rsd_info table during the  initialization of RSD instance using docker-compose.yml that uses `RSD_REMOTE_NAME` environment variable (see docker-compose.yml and .env.example).
+:::
+
 ## Error logs
 
 This section shows any errors originating from the background processes like data scrapers. Provided information should be understandable to rsd administrators in the most cases. The error object contains error response. The stacktrace is convenient for the programmers. The link will navigate you to the software or the project that triggers the error.

diff --git a/documentation/docs/03-rsd-instance/03-administration.md.license b/documentation/docs/03-rsd-instance/03-administration.md.license
@@ -1,8 +1,8 @@
 SPDX-FileCopyrightText: 2023 - 2024 Dusan Mijatovic (Netherlands eScience Center)
+SPDX-FileCopyrightText: 2023 - 2024 Dusan Mijatovic (dv4all) (dv4all)
 SPDX-FileCopyrightText: 2023 - 2024 Ewan Cahen (Netherlands eScience Center) <e.cahen@esciencecenter.nl>
 SPDX-FileCopyrightText: 2023 - 2024 Netherlands eScience Center
-SPDX-FileCopyrightText: 2023 Dusan Mijatovic (dv4all) (dv4all)
-SPDX-FileCopyrightText: 2023 dv4all
+SPDX-FileCopyrightText: 2023 - 2024 dv4all
 SPDX-FileCopyrightText: 2024 Christian Meeßen (GFZ) <christian.meessen@gfz-potsdam.de>
 SPDX-FileCopyrightText: 2024 Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences
 

diff --git a/documentation/docs/03-rsd-instance/img/admin-remotes.gif b/documentation/docs/03-rsd-instance/img/admin-remotes.gif
diff --git a/documentation/docusaurus.config.js b/documentation/docusaurus.config.js
@@ -1,5 +1,5 @@
-// SPDX-FileCopyrightText: 2023 Dusan Mijatovic (Netherlands eScience Center)
-// SPDX-FileCopyrightText: 2023 Netherlands eScience Center
+// SPDX-FileCopyrightText: 2023 - 2024 Dusan Mijatovic (Netherlands eScience Center)
+// SPDX-FileCopyrightText: 2023 - 2024 Netherlands eScience Center
 // SPDX-FileCopyrightText: 2024 Christian Meeßen (GFZ) <christian.meessen@gfz-potsdam.de>
 // SPDX-FileCopyrightText: 2024 Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences
 //
@@ -15,6 +15,9 @@ import {themes as prismThemes} from 'prism-react-renderer';
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
+  future: {
+    experimental_faster: true,
+  },
   title: 'RSD documentation',
   tagline: 'RSD documentation',
   favicon: 'favicon.ico',