Generate config documentation from application.properties

Leverages the `GenerateConfigDocs` JBang script (https://github.com/DependencyTrack/jbang-catalog/blob/main/GenerateConfigDocs.java) to generate reference documentation from the `application.properties` file. This makes `application.properties` the single source of truth for configuration options. We no longer need to copy-paste its contents to multiple places for documentation purposes. The documentation is re-generated automatically whenever `application.properties` changes. This is already done for the Hyades project (https://github.com/DependencyTrack/hyades/blob/2f95363fbf51423876a8eb2c7f0bc55a53ba85f9/DEVELOPING.md?plain=1#L11-L61) and turned out to be useful, so backporting it here. Signed-off-by: nscuro <[email protected]>
DependencyTrack · Sep 19, 2024 · 639a4a6 · 639a4a6
1 parent 18d00cf
commit 639a4a6
Show file tree

Hide file tree

Showing 19 changed files with 3,342 additions and 773 deletions.
diff --git a/.github/workflows/update-config-docs.yml b/.github/workflows/update-config-docs.yml
@@ -0,0 +1,62 @@
+# This file is part of Dependency-Track.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) OWASP Foundation. All Rights Reserved.
+name: Update Config Documentation
+
+on:
+  push:
+    branches:
+    - master
+    paths:
+    - ".github/workflows/update-config-docs.yml"
+    - "dev/scripts/config-docs.md.peb"
+    - "src/main/resources/application.properties"
+  workflow_dispatch: { }
+
+permissions: { }
+
+jobs:
+  generate-docs:
+    name: Generate Documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+      pull-requests: write
+    if: "${{ github.repository_owner == 'DependencyTrack' }}"
+    steps:
+    - name: Checkout Repository
+      uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # tag=v4.1.6
+    - name: Generate Documentation
+      uses: jbangdev/jbang-action@74844c9631cf1f35650427323e9bb3ffa41dfbd9 # tag=v0.115.0
+      with:
+        trust: https://github.com/DependencyTrack/jbang-catalog
+        script: gen-config-docs@DependencyTrack
+        scriptargs: >-
+          --template ./dev/scripts/config-docs.md.peb
+          --output docs/_docs/getting-started/configuration-apiserver.md
+          ./src/main/resources/application.properties
+    - name: Create Pull Request
+      uses: peter-evans/create-pull-request@6d6857d36972b65feb161a90e484f2984215f83e # tag=v6.0.5
+      with:
+        add-paths: "docs/_docs/getting-started/configuration-apiserver.md"
+        branch: update-config-docs
+        body: "Updates configuration documentation."
+        commit-message: Update config docs
+        delete-branch: true
+        labels: documentation
+        signoff: true
+        title: Update config docs
diff --git a/dev/scripts/config-docs.md.peb b/dev/scripts/config-docs.md.peb
@@ -0,0 +1,163 @@
+---
+title: Configuration - API Server
+category: Getting Started
+chapter: 1
+order: 7
+---
+<!--
+  GENERATED. DO NOT EDIT.
+
+  Generated with: {{ generateCommand }}
+-->
+
+The central configuration file `application.properties` resides in the classpath of the WAR by default.
+This configuration file controls many performance tuning parameters but is most useful for defining
+optional external database sources, directory services (LDAP), and proxy settings.
+
+For containerized deployments, the properties defined in the configuration file can also be specified
+as environment variables. All environment variables are upper case with periods (.) replaced with underscores (_).
+Refer to the [Docker instructions]({{ "{{ site.baseurl }}{% link _docs/getting-started/deploy-docker.md %}" }}) for
+configuration examples using environment variables.
+
+Dependency-Track administrators are highly encouraged to create a copy of this file in the
+Dependency-Track data directory and customize it prior to deploying to production.
+
+
+> The default embedded H2 database is designed to quickly evaluate and experiment with Dependency-Track.
+> Do not use the embedded H2 database in production environments.
+>
+> See: [Database Support]({{ "{{ site.baseurl }}{% link _docs/getting-started/database-support.md %}" }}).
+
+
+To start Dependency-Track using custom configuration, add the system property
+`alpine.application.properties` when executing. For example:
+
+```bash
+-Dalpine.application.properties=~/.dependency-track/application.properties
+```
+
+### Proxy Configuration
+
+Proxy support can be configured in one of two ways, using the proxy settings defined
+in `application.properties` or through environment variables. By default, the system
+will attempt to read the `https_proxy`, `http_proxy` and `no_proxy` environment variables. If one
+of these are set, Dependency-Track will use them automatically.
+
+`no_proxy` specifies URLs that should be excluded from proxying.
+This can be a comma-separated list of hostnames, domain names, or a mixture of both.
+If a port number is specified for a URL, only the requests with that port number to that URL will be excluded from proxying.
+`no_proxy` can also set to be a single asterisk ('*') to match all hosts.
+
+Dependency-Track supports proxies that require BASIC, DIGEST, and NTLM authentication.
+
+### Logging Levels
+
+Logging levels (INFO, WARN, ERROR, DEBUG, TRACE) can be specified by passing the level
+to the `dependencyTrack.logging.level` system property on startup. For example, the
+following command will start Dependency-Track (embedded) with DEBUG logging:
+
+```bash
+java -Xmx4G -DdependencyTrack.logging.level=DEBUG -jar dependency-track-embedded.war
+```
+
+For Docker deployments, simply set the `LOGGING_LEVEL` environment variable to one of
+INFO, WARN, ERROR, DEBUG, or TRACE.
+
+### Secret Key
+
+Dependency-Track will encrypt certain confidential data (e.g. access tokens for external service providers) with AES256
+prior to storing it in the database. The secret key used for encrypting and decrypting will be automatically generated
+when Dependency-Track starts for the first time, and is placed in `<alpine.data.directory>/keys/secret.key`
+(`/data/.dependency-track/keys/secret.key` for containerized deployments).
+
+Starting with Dependency-Track 4.7, it is possible to change the location of the secret key via the `alpine.secret.key.path`
+property. This makes it possible to use Kubernetes secrets for example, to mount secrets into the custom location.
+
+Secret keys may be generated manually upfront instead of relying on Dependency-Track to do it. This can be achieved
+with OpenSSL like this:
+
+```shell
+openssl rand 32 > secret.key
+```
+
+> Note that the default key format has changed in version 4.7. While existing keys using the old format will continue
+> to work, keys for new instances will be generated in the new format. Old keys may be converted using the following
+> [JShell](https://docs.oracle.com/en/java/javase/17/jshell/introduction-jshell.html) script:
+> ```java
+> import java.io.ObjectInputStream;
+> import java.nio.file.Files;
+> import java.nio.file.Paths;
+> import javax.crypto.SecretKey;
+> String inputFilePath = System.getProperty("secret.key.input")
+> String outputFilePath = System.getProperty("secret.key.output");
+> SecretKey secretKey = null;
+> System.out.println("Reading old key from " + inputFilePath);
+> try (var fis = Files.newInputStream(Paths.get(inputFilePath));
+>      var ois = new ObjectInputStream(fis)) {
+>     secretKey = (SecretKey) ois.readObject();
+> }
+> System.out.println("Writing new key to " + outputFilePath);
+> try (var fos = Files.newOutputStream(Paths.get(outputFilePath))) {
+>     fos.write(secretKey.getEncoded());
+> }
+> /exit
+> ```
+> Example execution:
+> ```shell
+> jshell -R"-Dsecret.key.input=$HOME/.dependency-track/keys/secret.key" -R"-Dsecret.key.output=secret.key.new" convert-key.jsh
+> ```
+
+---
+
+## Reference
+
+<ul>
+{% for entry in propertiesByCategory %}
+  <li><a href="#{{ entry.key | lower | replace({' ': '-'}) }}">{{ entry.key }}</a></li>
+{% endfor %}
+</ul>
+
+{% for entry in propertiesByCategory %}
+### {{ entry.key }}
+
+{% for property in entry.value -%}
+#### {{ property.name }}
+
+{{ property.description | replace({'  ': '
+'}) }}
+
+<table>
+  <tbody style="border: 0">
+    <tr>
+      <th style="text-align: right">Required</th>
+      <td style="border-width: 0">{{ property.required ? "Yes" : "No" }}</td>
+    </tr>
+    <tr>
+      <th style="text-align: right">Type</th>
+      <td style="border-width: 0">{{ property.type }}</td>
+    </tr>
+    {% if property.validValues -%}
+    <tr>
+      <th style="text-align: right">Valid Values</th>
+      <td style="border-width: 0">{{ property.validValues }}</td>
+    </tr>
+    {% endif -%}
+    <tr>
+      <th style="text-align: right">Default</th>
+      <td style="border-width: 0">{{ property.defaultValue }}</td>
+    </tr>
+    {% if property.example -%}
+    <tr>
+      <th style="text-align: right">Example</th>
+      <td style="border-width: 0">{{ property.example }}</td>
+    </tr>
+    {% endif -%}
+    <tr>
+      <th style="text-align: right">ENV</th>
+      <td style="border-width: 0">{{ property.env }}</td>
+    </tr>
+  </tbody>
+</table>
+
+{% endfor %}
+{% endfor %}
diff --git a/docs/Gemfile b/docs/Gemfile
@@ -11,4 +11,6 @@ group :jekyll_plugins do
   gem 'jekyll-sitemap', '1.4.0'
   gem 'jekyll-redirect-from', '0.16.0'
   gem 'jekyll-mermaid', '1.0.0'
+  # https://github.com/ffi/ffi/issues/1103#issuecomment-2186974923
+  gem 'ffi', '< 1.17.0'
 end
diff --git a/docs/_docs/datasources/snyk.md b/docs/_docs/datasources/snyk.md
@@ -93,7 +93,7 @@ When evaluating the severity of a vulnerability, it's important to note that the
 **NOTE:** For Beta version, user can select either from NVD or SNYK to prioritize the cvss vectors.
 
 [Authentication for API]: https://docs.snyk.io/snyk-api-info/authentication-for-api
-[Configuration]: {{ site.baseurl }}{% link _docs/getting-started/configuration.md %}
+[Configuration]: {{ site.baseurl }}{% link _docs/getting-started/configuration-apiserver.md %}
 [Finding the Snyk ID and internal name of an Organization]: https://docs.snyk.io/products/snyk-code/cli-for-snyk-code/before-you-start-set-the-organization-for-the-cli-tests/finding-the-snyk-id-and-internal-name-of-an-organization
 [Monitoring]: {{ site.baseurl }}{% link _docs/getting-started/monitoring.md %}#retries
 [REST API documentation]: https://apidocs.snyk.io