Software-Improvement-Group · fonteijnf · Feb 24, 2025 · Feb 6, 2025 · Feb 6, 2025 · Feb 6, 2025
diff --git a/README.md b/README.md
@@ -29,7 +29,7 @@ You can find more information on how to set up this development process integrat
 ## Sigrid REST API
 
 In addition to the [Sigrid user interface at sigrid-says.com](https://sigrid-says.com), you can also consume Sigrid's data via the Sigrid REST API. 
-You can find more information on how to use this API in the [Sigrid documentation](https://docs.sigrid-says.com/reference/sigrid-api-documentation.html). 
+You can find more information on how to use this API in the [Sigrid documentation](https://docs.sigrid-says.com/integrations/sigrid-api-documentation.html). 
 
 ## Contact and support
 

diff --git a/docs/_includes/menu.html b/docs/_includes/menu.html
@@ -20,9 +20,10 @@
             <a href="/organization-integration/upload-instructions.html" class="page">Uploading your source code</a>
             <a href="/organization-integration/metadata.html" class="page">Adding context using metadata</a>
             <a href="/organization-integration/systems.html" class="page">Mapping repositories to systems</a>
-            <a href="/organization-integration/onpremise-integration.html" class="page">Sigrid on-premise integration</a>
+            <a href="/organization-integration/onpremise-integration.html" class="page">Sigrid On-Premise integration</a>
             <a href="/organization-integration/onpremise-kubernetes.html" class="page subPage">Kubernetes configuration</a>
             <a href="/organization-integration/onpremise-analysis.html" class="page subPage">Analysis configuration</a>
+            <a href="/organization-integration/onpremise-runbooks.html" class="page subPage">Runbooks</a>
         </div>
 
         <div class="category">Sigrid: Portfolio-level capabilities</div>

diff --git a/docs/organization-integration/onpremise-analysis.md b/docs/organization-integration/onpremise-analysis.md
@@ -7,7 +7,7 @@ This documentation covers on-premise Sigrid. It is not applicable for cloud-base
 
 ## Prerequisites
 
-Your development platform will need access to the [Sigrid on-premise Docker containers](onpremise-integration.md#obtaining-sigrid-on-premise).
+Your development platform will need access to the [Sigrid On-Premise Docker containers](onpremise-integration.md#obtaining-sigrid-on-premise).
 
 Each system to be analyzed needs an analysis configuration in the form of a file called
 `sigrid.yaml` in the root directory of the system. Typically, this configuration is maintained by
@@ -111,7 +111,7 @@ Notes:
 - `SYSTEM`: the name of this system (a lowercase string matching `[a-z][a-z0-9-]`). The default is 
   the project name of the current CI/CD project (e.g., the pre-configured `$CI_PROJECT_NAME` 
   variable in GitLab).
-- `SIGRID_URL`: (sub-)domain where this Sigrid on-premise deployment is hosted, e.g. 
+- `SIGRID_URL`: (sub-)domain where this Sigrid On-Premise deployment is hosted, e.g. 
   `https://sigrid.mycompany.com`.
 - `SIGRID_CI_TOKEN`: a personal access token created in Sigrid's UI.
 - `BUCKET`: name of the bucket in which analysis results are stored.
@@ -267,7 +267,7 @@ The following example shows how to start an ad-hoc analysis for a system located
       -ti softwareimprovementgroup/sigrid-multi-analyzer:$SIGRID_VERSION \
       --publish
 
-This requires you to have access to the [Sigrid on-premise Docker containers](onpremise-integration.md#obtaining-sigrid-on-premise).
+This requires you to have access to the [Sigrid On-Premise Docker containers](onpremise-integration.md#obtaining-sigrid-on-premise).
 
 The version tag (`$SIGRID_VERSION`) should match your version of Sigrid on-premise. 
 

diff --git a/docs/organization-integration/onpremise-integration.md b/docs/organization-integration/onpremise-integration.md
@@ -1,9 +1,9 @@
-# Sigrid on-premise integration
+# Sigrid On-Premise integration
 
 This documentation covers on-premise Sigrid. It is not applicable for cloud-based Sigrid.
 {: .attention }
 
-This document covers everything you need to integrate Sigrid on-premise in your environment. It also covers the functional differences between the SaaS version and the on-premise version, though these differences are relatively minor.
+This document covers everything you need to integrate Sigrid On-Premise in your environment. It also covers the functional differences between the SaaS version and the on-premise version, though these differences are relatively minor.
 
 <sig-toc></sig-toc>
 
@@ -16,15 +16,15 @@ From a deployment perspective, on-premise Sigrid consists of two "parts":
 
 <img src="../images/onpremise-overview.png" width="600" />
 
-- Sigrid on-premise is based on [Docker containers](https://en.wikipedia.org/wiki/Docker_%28software%29). There are two types of containers:
+- Sigrid On-Premise is based on [Docker containers](https://en.wikipedia.org/wiki/Docker_%28software%29). There are two types of containers:
   - Application containers that should be deployed permanently in a [Kubernetes](https://en.wikipedia.org/wiki/Kubernetes) cluster, based on a [Helm chart](https://helm.sh) that is provided by SIG.
   - Analysis containers that run from a build pipeline within your development platform. These analysis containers may also be started on Kubernetes, but that is not a requirement. Supported development platforms are listed in [development platform integration](#development-platform-integration).
 - SIG provides the necessary images through a container registry. The section [obtaining Sigrid on-premise](#obtaining-sigrid-on-premise) contains more information on how you can obtain and update these Docker containers.
 - Authentication is based on your identity provider, using [OpenID Connect](https://openid.net/developers/how-connect-works/). Alternatively, [SAML](https://en.wikipedia.org/wiki/SAML_2.0) or [LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol) are also supported, through [Dex](https://dexidp.io/).
 - Analyses are triggered from a build pipeline. The analysis results are then imported into a Postgres database, so they can be viewed in Sigrid.
 - Large files are stored in an [S3-compatible object store](https://aws.amazon.com/s3/).
 
-Some Sigrid on-premise features are *optional*:
+Some Sigrid On-Premise features are *optional*:
 
 - The Open Source Health feature requires outbound internet access. Sigrid needs to connect to external sources to check for the latest vulnerability data for open source libraries. If you do not allow outbound internet access, the Open Source Health feature is not available. The rest of Sigrid is unaffected.
 - When viewing detailed analysis results, Sigrid displays relevant source code files within Sigrid. For this to work, a web-accessible code storage needs to be available. This integrates with Sigrid via [OAuth](https://oauth.net/2/). For this to work, the identity provider used for Sigrid authentication and for the code storage needs to be the same. For viewing source code within Sigrid, you need to provide a development platform that is integrated with the same identity provider as Sigrid itself. The view source functionality is optional, without this integration the rest of Sigrid is unaffected.
@@ -45,7 +45,7 @@ Some Sigrid on-premise features are *optional*:
 
 ## Obtaining Sigrid on-premise
 
-The Docker containers that form Sigrid on-premise are distributed via [DockerHub](https://hub.docker.com). You will receive an account that allows you to access the container registry. 
+The Docker containers that form Sigrid On-Premise are distributed via [DockerHub](https://hub.docker.com). You will receive an account that allows you to access the container registry. 
 
 <img src="../images/onpremise-dockerhub.png" width="500" /> 
 
@@ -60,7 +60,7 @@ Instructions for installing and configuring both parts are provided in the follo
 - [Sigrid on-premise: Helm Chart configuration](onpremise-kubernetes.md)
 - [Sigrid on-premise: Analysis configuration](onpremise-analysis.md)
 
-## Updating Sigrid on-premise to a new version
+## Updating Sigrid On-Premise to a new version
 
 SIG releases the Sigrid Docker containers based on a [continuous delivery](https://en.wikipedia.org/wiki/Continuous_delivery) process. This means that changes are immediately released once they have successfully passed through the development process. We advise our clients on the best way to develop and operate their software, so we try to adhere to the same best practices that we recommend our clients. 
 

diff --git a/docs/organization-integration/onpremise-kubernetes.md b/docs/organization-integration/onpremise-kubernetes.md
@@ -7,7 +7,7 @@ This documentation describes how to configure on-premise Sigrid, so you can depl
 using a [Helm](https://helm.sh) chart provided by SIG. 
 
 To use this Helm chart, it needs to be configured by providing your own `values.yaml`, as is typical 
-for Helm. The current page describes how to deploy Sigrid on-premise in terms of the available 
+for Helm. The current page describes how to deploy Sigrid On-Premise in terms of the available 
 configuration options in `values.yaml`. It is based on the `example-values.yaml` file available 
 in the Helm chart, which provides examples of typical configuration values.
 
@@ -55,7 +55,7 @@ The Helm chart gives precedence to the values for registry and repository set sp
 component and falls back to the global `imageRegistry` if needed. Keep in mind that some 
 sub-charts behave in a different way, or do not honor `imageRegistry` at all. 
 
-For air-gapped Sigrid on-premise deployments, images are typically pulled regularly to an 
+For air-gapped Sigrid On-Premise deployments, images are typically pulled regularly to an 
 internal image registry first; the (air-gapped) Kubernetes cluster then pulls from this registry.
 In this case, it is best to point the global `imageRegistry` setting to the internal image registry.
 It is, however, always possible to set the registry per component of Sigrid by using one or more 
@@ -68,7 +68,7 @@ sigrid-api:
     tag: "some-tag"
 ```
 
-Sigrid on-premise needs access to the following images published on [SIG's private Docker Hub]
+Sigrid On-Premise needs access to the following images published on [SIG's private Docker Hub]
 (https://hub.docker.com/u/softwareimprovementgroup):
 
 - `softwareimprovementgroup/ai-explanation-service`
@@ -308,7 +308,7 @@ UWTs are JSON web tokens and hence need to be signed. This means a keypair needs
 configured that Sigrid uses to sign UWTs. The steps are as follows:
 1. Create a 2048-bit RSA keypair, for instance using OpenSSL. The key needs to be in PEM format 
    (this format is easy to recognize: it is an ASCII file starting with `-----BEGIN PRIVATE 
-   KEY-----`). When using OpenSSL, the command is `openssl genrsa -out uwt_signing_key.pem 2048`.
+   KEY-----`). When using OpenSSL, the command is `openssl genpkey -out uwt_signing_key.pem -algorithm RSA -pkeyopt rsa_keygen_bits:2048`.
 2. Create a Kubernetes secret to hold this key. This secret needs to be an opaque secret with 
    two properties: `issuer-uri` (typically: `https://your-sigrid-domain`) and `private-key` (which 
    holds the keypair in PEM format created in step 1). 

diff --git a/docs/organization-integration/onpremise-runbooks.md b/docs/organization-integration/onpremise-runbooks.md
@@ -0,0 +1,22 @@
+# Sigrid On-Premise: Runbooks
+
+This documentation covers on-premise Sigrid. It is not applicable for cloud-based Sigrid.
+{: .attention }
+
+The following runbooks offer simplified steps and useful context for configuring and maintaining your on-premise Sigrid, providing an excellent starting point if you're unsure where to begin.
+
+<sig-toc></sig-toc>
+
+## Prerequisites
+
+- You should have already read the other Sigrid On-Premise documentation
+- You have access to Software Improvement Group DockerHub
+
+## Runbooks
+
+- [Runbook: Sigrid On-Premise Installation](runbook-onpremise-installation.md)
+- [Runbook: Sigrid On-Premise Updating](runbook-onpremise-updating.md)
+
+## Contact and support
+
+Feel free to contact [SIG's support department](mailto:[email protected]) for any questions or issues you may have after reading this document, or when using Sigrid or Sigrid CI. Users in Europe can also contact us by phone at +31 20 314 0953.