Improve documentation for integrations app settings #31

Signed-off-by: tdruez <tdruez@nexb.com>

Author: tdruez

docs/application-settings.rst

@@ -63,34 +63,6 @@ responsible to provide your own validation of the Host header.
 
     ALLOWED_HOSTS=*
 
-.. _dejacode_settings_purldb:
-
-PURLDB
-------
-
-Provide the URL and API key of your `PurlDB <https://github.com/nexB/purldb/>`_
-instance.
-
-::
-
-    PURLDB_URL=https://your-purldb-domain/
-    PURLDB_API_KEY=apikeyexample
-
-.. _dejacode_settings_vulnerablecode:
-
-VULNERABLECODE
---------------
-
-You can either run your own instance of
-`VulnerableCode <https://github.com/nexB/vulnerablecode/>`_
-or connect to the public one.
-
-Authentication is provided using an API key that you can obtain by registering at
-https://public.vulnerablecode.io/account/request_api_key/ ::
-
-    VULNERABLECODE_URL=https://public.vulnerablecode.io/
-    VULNERABLECODE_API_KEY=apikeyexample
-
 EMAIL
 -----
 
@@ -187,11 +159,11 @@ to provide some progress about pipeline run execution.
 
 Default: ``INFO``
 
-The ``DEBUG`` value can be provided to this setting to see all ScanCode.io debug
+The ``DEBUG`` value can be provided to this setting to see all DejaCode debug
 messages to help track down configuration issues for example.
 This mode can be enabled globally through the ``.env`` file::
 
-    SCANCODEIO_LOG_LEVEL=DEBUG
+    DEJACODE_LOG_LEVEL=DEBUG
 
 .. _clamd-settings:
 
@@ -222,6 +194,65 @@ default the ``US/Pacific`` time zone is used::
     You can view a detailed list of time zones `here.
     <https://en.wikipedia.org/wiki/List_of_tz_database_time_zones>`_
 
+.. _dejacode_settings_aboutcode_integrations:
+
+AboutCode integrations
+======================
+
+To **integrate DejaCode with other applications within the AboutCode stack**,
+you have the flexibility to configure and set up integrations using the following
+application settings.
+
+It's important to understand that employing application settings will make these
+integrations **globally accessible across all Dataspaces** within your DejaCode
+instance.
+
+Alternatively, if you wish to tailor the availability of these features to a specific
+Dataspace, you can define and set those values directly within the Dataspace
+configuration. This can be done through the Dataspace admin UI, allowing you to scope
+the availability of these integrations exclusively to the designated Dataspace.
+
+.. _dejacode_settings_scancodeio:
+
+SCANCODEIO
+----------
+
+Provide the URL and API key of your `ScanCode.io <https://github.com/nexB/scancode.io>`_
+instance.
+
+.. code-block:: python
+
+    SCANCODEIO_URL=https://your_scancodeio.url/
+    SCANCODEIO_API_KEY=insert_your_api_key_here
+
+.. _dejacode_settings_purldb:
+
+PURLDB
+------
+
+Provide the URL and API key of your `PurlDB <https://github.com/nexB/purldb>`_ instance.
+
+.. code-block:: python
+
+    PURLDB_URL=https://your-purldb.url/
+    PURLDB_API_KEY=insert_your_api_key_here
+
+.. _dejacode_settings_vulnerablecode:
+
+VULNERABLECODE
+--------------
+
+You can either run your own instance of
+`VulnerableCode <https://github.com/nexB/vulnerablecode>`_
+or connect to the public one https://public.vulnerablecode.io/.
+
+.. note:: Providing an API key is optional when using the public VulnerableCode instance.
+
+.. code-block:: python
+
+    VULNERABLECODE_URL=https://public.vulnerablecode.io/
+    VULNERABLECODE_API_KEY=insert_your_api_key_here
+
 LDAP Integration
 ================
 

docs/dataspace.rst

@@ -278,6 +278,8 @@ The basic techniques to use in your own Dataspace are:
    **Set usage policy from licenses** option in the dropdown list in the lower
    right hand corner of the form and follow the prompts to complete that action.
 
+.. _dejacode_dataspace_scancodeio:
+
 Enable package scanning with your ScanCode.io server
 ====================================================
 
@@ -344,6 +346,8 @@ You can:
 You can now access the **Scans** section from the **Tools** menu and request package
 scans from this view.
 
+.. _dejacode_dataspace_purldb:
+
 Enable PurlDB service
 =====================
 
@@ -393,6 +397,8 @@ You can:
 You can now access the **PurlDB** section from the **Tools** menu and browse package
 from this view.
 
+.. _dejacode_dataspace_vulnerablecode:
+
 Enable VulnerableCodeDB service
 ===============================
 

docs/installation.rst

@@ -33,7 +33,7 @@ Refer to Docker's documentation for the best installation path for your system:
 
    <a href="https://docs.docker.com/get-docker/" target="_blank" class="external">Get Docker</a>
 
-2. Build the Image
+2. Build the image
 ------------------
 
 DejaCode comes with the necessary ``Dockerfile`` and ``docker-compose.yml`` files to
@@ -60,7 +60,7 @@ Create an **environment file**, and **build the Docker image** with::
     cd dejacode && make envfile
     docker compose build
 
-3. Run the App
+3. Run the app
 --------------
 
 To **run the DejaCode images as containers**, use the following command::
@@ -107,23 +107,35 @@ Use these credentials to access the application.
     For example, with Docker configured for 8 CPUs, allocate a minimum of 8 GB of
     memory.
 
+5. Setup AboutCode integrations
+-------------------------------
+
+You can enable DejaCode integrations with other applications in the AboutCode stack.
+
+- **ScanCode.io**: Enable package scanning.
+  Refer to :ref:`dejacode_dataspace_scancodeio`.
+- **PurlDB**: Access a database of scanned packages.
+  Refer to :ref:`dejacode_dataspace_purldb`.
+- **VulnerableCodeDB**: Access a database of package vulnerabilities.
+  Refer to :ref:`dejacode_dataspace_vulnerablecode`.
+
 Hardware requirements
 =====================
 
 The minimum hardware/system requirements for running DejaCode as an enterprise
 server are:
 
-+-----------+----------------------------------------------------------------+
-| Item      | Minimum                                                        |
-+===========+================================================================+
-| Processor | Modern X86 64 bits Intel Quad Core or better, or equivalent    |
-+-----------+----------------------------------------------------------------+
-| Memory    | 64 GB or more (ECC preferred)                                  |
-+-----------+----------------------------------------------------------------+
-| Disk      | 2 * 500GB SDD in RAID mirror setup (enterprise disk preferred) |
-+-----------+----------------------------------------------------------------+
-| OS        | Ubuntu 22.04 LTS 64-bit server clean installation              |
-+-----------+----------------------------------------------------------------+
++-----------+------------------------------------------------------------------+
+| Item      | Minimum                                                          |
++===========+==================================================================+
+| Processor | Modern X86 64 bit Multi Core, with at least **4 physical cores** |
++-----------+------------------------------------------------------------------+
+| Memory    | **64 GB** or more (ECC preferred)                                |
++-----------+------------------------------------------------------------------+
+| Disk      | 2 * 500GB SDD in RAID mirror setup (enterprise disk preferred)   |
++-----------+------------------------------------------------------------------+
+| OS        | **Ubuntu 22.04 LTS 64-bit** server clean installation            |
++-----------+------------------------------------------------------------------+
 
 .. _local_development_installation: