Skip to content

Commit 43f031a

Browse files
schwzrschwzr
committed
v2.1.0 initial docs
1 parent a36bce2 commit 43f031a

31 files changed

Lines changed: 4973 additions & 8 deletions

‎docs/src/.vuepress/components/ImageVerification.vue‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<template>
2+
<div class="image-verification">
3+
<h2>Verify Image Signature</h2>
4+
<p>
5+
The <code>{{ image }}</code> image is signed using
6+
<a href="https://docs.sigstore.dev/cosign/overview/" target="_blank" rel="noopener">Cosign</a>
7+
keyless signing via the official DSF GitHub Actions release workflow.
8+
Verify the signature before using the image in production:
9+
</p>
10+
<pre><code>cosign verify \
11+
ghcr.io/datasharingframework/{{ image }}:{{ tag }}@sha256:{{ digestDisplay }} \
12+
--certificate-identity-regexp "https://github.com/datasharingframework/dsf/.*" \
13+
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"</code></pre>
14+
<p v-if="!digest">
15+
Replace <code>&lt;digest&gt;</code> with the immutable digest of the image
16+
you intend to deploy. See
17+
<a :href="guide">How to Verify Image Signatures</a>
18+
for the complete guide, SBOM verification, and troubleshooting.
19+
</p>
20+
<p v-else>
21+
See <a :href="guide">How to Verify Image Signatures</a> for the complete
22+
guide, SBOM verification, and troubleshooting.
23+
</p>
24+
</div>
25+
</template>
26+
27+
<script>
28+
export default {
29+
props: {
30+
image: { type: String, required: true },
31+
tag: { type: String, default: '2.1.0' },
32+
digest: { type: String, default: '' },
33+
guide: { type: String, default: '../image-verification' }
34+
},
35+
computed: {
36+
digestDisplay() {
37+
return this.digest ? this.digest.replace(/^sha256:/, '') : '<digest>';
38+
}
39+
}
40+
}
41+
</script>

‎docs/src/.vuepress/layouts/PageLayout.vue‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import { useRoute, useRouter } from "vue-router";
44
import { ref, onMounted } from 'vue'
55
66
const version = ref("");
7-
const latestVersion = "v2.0.2";
7+
const latestVersion = "v2.1.0";
88
99
1010
function setVersionBasedOnCurrentPath() : void {
@@ -55,7 +55,8 @@ function navigateToNewVersion() {
5555
<div class="version-selector" v-if="route.path.startsWith('/operations/')">
5656
<label class="vp-sidebar-header" for="version-select"><strong>Version:</strong> </label>
5757
<select id="version-select" class="vp-sidebar-header" v-model="version" @change="navigateToNewVersion">
58-
<option value="v2.0.2">latest (2.0.2)</option>
58+
<option value="v2.1.0">latest (2.1.0)</option>
59+
<option value="v2.0.2">2.0.2</option>
5960
<option value="v2.0.1">2.0.1</option>
6061
<option value="v2.0.0">2.0.0</option>
6162
<option value="v1.9.0">1.9.0</option>

‎docs/src/.vuepress/sidebar/operations-v2.ts‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,16 @@ export function generate_v2_latest_sidebar() {
44
icon: "tool",
55
link: "./",
66
},
7-
"release-notes", "install", "upgrade-from-2", "upgrade-from-1", "allowList-mgm", "root-certificates", "passwords-secrets", {
7+
"release-notes", "install", "upgrade-from-2", "upgrade-from-1", "allowList-mgm", "root-certificates", "passwords-secrets", "image-verification", {
88
text: "FHIR Reverse Proxy",
99
icon: "module",
10+
prefix: "fhir-reverse-proxy/",
11+
link: "fhir-reverse-proxy/",
1012
children: [
1113
{
1214
icon: "config",
1315
text: "Configuration",
14-
link: "fhir-reverse-proxy/configuration",
16+
link: "configuration",
1517
}
1618
]
1719
},
@@ -40,11 +42,13 @@ export function generate_v2_latest_sidebar() {
4042
}, {
4143
text: "BPE Reverse Proxy",
4244
icon: "module",
45+
prefix: "bpe-reverse-proxy/",
46+
link: "bpe-reverse-proxy/",
4347
children: [
4448
{
4549
icon: "config",
4650
text: "Configuration",
47-
link: "bpe-reverse-proxy/configuration",
51+
link: "configuration",
4852
}
4953
]
5054
}, {

‎docs/src/.vuepress/theme.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ export default hopeTheme({
3939
icon: "launch",
4040
prefix: "/operations/",
4141
children: [ {
42-
text: "Current Version - 2.0.2",
42+
text: "Current Version - 2.1.0",
4343
link: "get-started.md",
4444
icon: "launch"
4545
}, "old-versions.md"],
@@ -127,7 +127,8 @@ export default hopeTheme({
127127
"/operations/old-versions": [],
128128
"/operations/latest/": generate_v2_latest_sidebar(),
129129
"/operations/next/": [],
130-
"/operations/v2.0.2/": generate_v2_latest_sidebar(),
130+
"/operations/v2.1.0/": generate_v2_latest_sidebar(),
131+
"/operations/v2.0.2/": generate_v2_0_0_sidebar(),
131132
"/operations/v2.0.1/": generate_v2_0_0_sidebar(),
132133
"/operations/v2.0.0/": generate_v2_0_0_sidebar(),
133134
"/operations/v1.9.0/": generate_v1_latest_sidebar(),

‎docs/src/operations/latest‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
v2.0.2
1+
v2.1.0

‎docs/src/operations/old-versions.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ icon: launch
55

66
## DSF v2
77

8+
- [2.1.0](./v2.1.0/)
89
- [2.0.1](./v2.0.1/)
910
- [2.0.0](./v2.0.0/)
1011

‎docs/src/operations/v2.1.0/allowList-mgm.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: Allow List Management
3+
icon: share
4+
---
5+
You can read all about the concept of Allow Lists [in our introduction](/explore/concepts/allow-list.md).
6+
7+
## Overview
8+
To simplify the DSF Allow List Management we have built a portal for administration. The portal is managed by the GECKO Institute at Heilbronn University. You as an DSF administrator can create or update your Allow List information. The information you provide on this portal will be transferred to us and will be used to built Allow List bundles that get distributed to the communication partners of the distributed processes.
9+
10+
The DSF Allow List management tool uses client certificates for authentication. You can either use a personal client certificate or the client certificate from your DSF BPE, which needs to be added to your web-browsers certificate store.
11+
12+
13+
## Prerequisites
14+
1. Deployed DSF instance (test or production infrastructure)
15+
1.1 If none exists yet, read [the installation guide](install)
16+
2. Certificate
17+
2.1 If none exists yet, read [the certificate requirements](install#client-server-certificates)
18+
3. Organization identifier, shortest FQDN of your organizations website, e.g. `my-hospital.de`
19+
4. FHIR endpoint URL, e.g. `https://dsf.my-hospital.de/fhir`
20+
5. Contact details from a responsible person of your organization
21+
6. Access to the E-Mail address from your organization for verification
22+
23+
24+
## Start here
25+
When you have fulfilled all the prerequisites, you can start managing your Allow Lists via the environment specific Allow List Management Tool:
26+
27+
- [**Test** infrastructure](https://allowlist-test.gecko.hs-heilbronn.de)
28+
- [**Production** infrastructure](https://allowlist.gecko.hs-heilbronn.de)
29+
30+
We use different highlight colors for the DSF Allow List Management Tool: Green for the **Test** environment and blue for the **Production** infrastructure. To access the site, you have to authenticate yourself with a client certificate. Your web-browser will show a dialog to choose a valid certificate.
31+
32+
::: tip Ideas for improvement?
33+
Have you found an error or is something unclear to you? Then please feel free to contact us on the <a href="https://mii.zulipchat.com/#narrow/stream/392426-Data-Sharing-Framework-.28DSF.29">MII-Zulip Channel</a> or write us at <a href="mailto:dsf-gecko@hs-heilbronn.de">dsf-gecko@hs-heilbronn.de</a>. Thank you very much!
34+
:::

‎docs/src/operations/v2.1.0/bpe-reverse-proxy/README.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
title: BPE Reverse Proxy
3+
icon: module
4+
---
5+
6+
## Purpose
7+
8+
The **DSF BPE Reverse Proxy** is an Apache HTTP Server based front for the [BPE Server](../bpe/).
9+
It terminates TLS for the BPE's web UI and OIDC-authenticated administrative
10+
endpoints, and forwards authenticated requests to the BPE backend. Unlike the
11+
[FHIR Reverse Proxy](../fhir-reverse-proxy/), it is intended for internal
12+
operator and administrator access only, not for DSF-to-DSF traffic.
13+
14+
## Docker Image
15+
16+
- Registry: [`ghcr.io/datasharingframework/bpe_proxy`](https://github.com/datasharingframework/dsf/pkgs/container/bpe_proxy)
17+
- Tag for this release: `2.1.0`
18+
19+
<ImageVerification image="bpe_proxy" tag="2.1.0" guide="../image-verification" />
20+
21+
## Useful Pages
22+
23+
- [Configuration Parameters](configuration)
24+
- [How to Verify Image Signatures](../image-verification)

‎docs/src/operations/v2.1.0/bpe-reverse-proxy/configuration.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
title: Configuration Parameters
3+
icon: config
4+
---
5+
6+
### APP_SERVER_IP
7+
- **Required:** Yes
8+
- **Description:** Hostname or IP-Address of the DSF BPE server application container, the reverse proxy target
9+
- **Example:** `app`, `172.28.1.3`
10+
11+
12+
### HTTPS_SERVER_NAME_PORT
13+
- **Required:** Yes
14+
- **Description:** FQDN of your DSF BPE server with port, typically `443`
15+
- **Example:** `my-external.fqdn:443`
16+
17+
18+
### PROXY_PASS_CONNECTION_TIMEOUT_HTTP
19+
- **Required:** No
20+
- **Description:** Connection timeout (seconds) for reverse proxy to app server http connection, time the proxy waits for a connection to be established
21+
- **Default:** `30` seconds
22+
23+
24+
### PROXY_PASS_CONNECTION_TIMEOUT_WS
25+
- **Required:** No
26+
- **Description:** Connection timeout (seconds) for reverse proxy to app server ws connection, time the proxy waits for a connection to be established
27+
- **Default:** `30` seconds
28+
29+
30+
### PROXY_PASS_TIMEOUT_HTTP
31+
- **Required:** No
32+
- **Description:** Timeout (seconds) for reverse proxy to app server http connection, time the proxy waits for a reply
33+
- **Default:** `60` seconds
34+
35+
36+
### PROXY_PASS_TIMEOUT_WS
37+
- **Required:** No
38+
- **Description:** Timeout (seconds) for reverse proxy to app server ws connection, time the proxy waits for a reply
39+
- **Default:** `60` seconds
40+
41+
42+
### SERVER_CONTEXT_PATH
43+
- **Required:** No
44+
- **Description:** Reverse proxy context path that delegates to the app server, `/` character at start, no `/` character at end, use `''` (empty string) to configure root as context path
45+
- **Default:** `/bpe`
46+
47+
48+
### SSL_CA_CERTIFICATE_FILE
49+
- **Required:** No
50+
- **Description:** Certificate chain file including all issuing, intermediate and root certificates used to validate client certificates, PEM encoded, sets the apache httpd parameter `SSLCACertificateFile`; not used by default, overrides *SSL_CA_CERTIFICATE_PATH* if not empty
51+
52+
53+
### SSL_CA_CERTIFICATE_PATH
54+
- **Required:** No
55+
- **Description:** Folder with trusted full CA chains for validating client certificates
56+
- **Recommendation:** Override default folder content via bind mount or add *.crt files to default folder via bind mount
57+
- **Default:** `ca/client_ca_chains`
58+
59+
60+
### SSL_CA_DN_REQUEST_FILE
61+
- **Required:** No
62+
- **Description:** File containing all signing certificates excepted, will be used to specify the `Acceptable client certificate CA names` send to the client, during TLS handshake, sets the apache httpd parameter `SSLCADNRequestFile`; if omitted all entries from *SSL_CA_CERTIFICATE_FILE* are used; not used by default, overrides *SSL_CA_DN_REQUEST_PATH* if not empty
63+
64+
65+
### SSL_CA_DN_REQUEST_PATH
66+
- **Required:** No
67+
- **Description:** Folder with trusted client certificate issuing CAs, modifies the "Acceptable client certificate CA names" send to the client, uses all from *SSL_CA_CERTIFICATE_FILE* or *SSL_CA_CERTIFICATE_PATH* if not set or empty
68+
- **Recommendation:** Override default folder content via bind mount or add *.crt files to default folder via bind mount
69+
- **Default:** `ca/client_issuing_cas`
70+
71+
72+
### SSL_CERTIFICATE_CHAIN_FILE
73+
- **Required:** No
74+
- **Description:** Certificate chain file, PEM encoded, must contain all certificates between the server certificate and the root ca certificate (excluding the root ca certificate), sets the apache httpd parameter `SSLCertificateChainFile`; can be omitted if either no chain is needed (self signed server certificate) or the file specified via *SSL_CERTIFICATE_FILE* contains the certificate chain
75+
- **Recommendation:** Use docker secret file to configure
76+
- **Example:** `/run/secrets/ssl_certificate_chain_file.pem`
77+
78+
79+
### SSL_CERTIFICATE_FILE
80+
- **Required:** Yes
81+
- **Description:** Server certificate file, PEM encoded, sets the apache httpd parameter `SSLCertificateFile`, may contain all certificates between the server certificate and the root ca certificate (excluding the root ca certificate). Omit *SSL_CERTIFICATE_CHAIN_FILE* if chain included
82+
- **Recommendation:** Use docker secret file to configure
83+
- **Example:** `/run/secrets/ssl_certificate_file.pem`
84+
85+
86+
### SSL_CERTIFICATE_KEY_FILE
87+
- **Required:** Yes
88+
- **Description:** Server certificate private key file, PEM encoded, unencrypted, sets the apache httpd parameter `SSLCertificateKeyFile`
89+
- **Recommendation:** Use docker secret file to configure
90+
- **Example:** `/run/secrets/ssl_certificate_key_file.pem`
91+
92+
93+
### SSL_EXPECTED_CLIENT_S_DN_C_VALUES
94+
- **Required:** No
95+
- **Description:** Expected client certificate subject DN country `C` values, must be a comma-separated list of strings in single quotation marks, e.g. `'DE', 'FR'`. If a client certificate with a not configured subject country `C` value is used, the server answers with a `403 Forbidden` status code
96+
- **Default:** `'DE'`
97+
98+
99+
### SSL_EXPECTED_CLIENT_I_DN_CN_VALUES
100+
- **Required:** No
101+
- **Description:** Expected client certificate issuer DN common-name `CN` values, must be a comma-separated list of strings in single quotation marks. If a client certificate from a not configured issuing ca common-name is used, the server answers with a `403 Forbidden` status code
102+
- **Default:** `'GEANT TLS ECC 1', 'HARICA OV TLS ECC', 'GEANT TLS RSA 1', 'HARICA OV TLS RSA', 'GEANT S/MIME ECC 1', 'HARICA Client Authentication ECC', 'HARICA S/MIME ECC', 'GEANT S/MIME RSA 1', 'HARICA Client Authentication RSA', 'HARICA S/MIME RSA', 'DFN-Verein Global Issuing CA', 'Fraunhofer User CA - G02', 'D-TRUST SSL Class 3 CA 1 2009', 'Sectigo RSA Organization Validation Secure Server CA', 'GEANT OV RSA CA 4', 'GEANT Personal CA 4', 'GEANT eScience Personal CA 4', 'Sectigo ECC Organization Validation Secure Server CA', 'GEANT OV ECC CA 4', 'GEANT Personal ECC CA 4', 'GEANT eScience Personal ECC CA 4', 'D-TRUST Limited Basic CA 1-2 2019', 'D-TRUST Limited Basic CA 1-3 2019'`
103+
104+
105+
### SSL_VERIFY_CLIENT
106+
- **Required:** No
107+
- **Description:** Modifies the apache mod_ssl config parameter `SSLVerifyClient`
108+
- **Recommendation:** Set to `optional` when using OIDC authentication
109+
- **Default:** `require`

‎docs/src/operations/v2.1.0/bpe/README.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: BPE Server
3+
icon: module
4+
---
5+
6+
## Purpose
7+
8+
The **DSF Business Process Engine (BPE)** executes the BPMN 2.0 workflows that
9+
drive distributed data sharing processes between DSF instances. It listens for
10+
new `Task` resources on the local FHIR Server, runs the corresponding process
11+
plugin, and creates follow-up `Task` resources on remote FHIR Servers via its
12+
configured FHIR client connections. The BPE is an internal component and is not
13+
exposed to the public network — it talks to local systeme (e.g., the local FHIR Store) and to remote
14+
DSF FHIR Servers through their reverse proxies.
15+
16+
## Docker Image
17+
18+
- Registry: [`ghcr.io/datasharingframework/bpe`](https://github.com/datasharingframework/dsf/pkgs/container/bpe)
19+
- Tag for this release: `2.1.0`
20+
21+
<ImageVerification image="bpe" tag="2.1.0" guide="../image-verification" />
22+
23+
## Useful Pages
24+
25+
- [Configuration Parameters](configuration)
26+
- [Access Control](access-control)
27+
- [OpenID Connect](oidc)
28+
- [Logging](logging)
29+
- [FHIR Client Connections](fhir-client-connections)
30+
- [How to Verify Image Signatures](../image-verification)

0 commit comments

Comments
 (0)