Added a FAQ section to the README

This is based on questions posed by a couple of sites and answered by
Tobias.
This commit is contained in:
DavidCroftDKFZ 2025-04-04 12:23:56 +02:00
parent 4ef585bfc5
commit 8e114f096a
1 changed files with 71 additions and 0 deletions

View File

@ -27,6 +27,7 @@ This repository is the starting point for any information and tools you will nee
- [Auto-Updates](#auto-updates)
- [Auto-Backups](#auto-backups)
- [Non-Linux OS](#non-linux-os)
- [FAQ](#faq)
5. [Troubleshooting](#troubleshooting)
- [Docker Daemon Proxy Configuration](#docker-daemon-proxy-configuration)
- [Monitoring](#monitoring)
@ -386,6 +387,76 @@ We have tested the installation procedure with an Ubuntu 22.04 guest system runn
Installation under WSL ought to work, but we have not tested this.
### FAQ
<details>
<summary><strong>Q: How is the security of GitHub pulls, volumes/containers, and image signing ensured?</strong></summary>
A: Changes to Git branches that could be delivered to sites (main and develop) must be accepted via a pull request with at least two positive reviews.
Containers/images are not built manually, but rather automatically through a CI/CD pipeline, so that an image can be rolled back to a defined code version at any time without changes.
**Note:** If firewall access for (outgoing) connections to GitHub and/or Docker Hub is problematic at the site, mirrors for both services are available, operated by the DKFZ.
</details>
<details>
<summary><strong>Q: How is authentication between users and components regulated?</strong></summary>
A: When setting up a Bridgehead, a private key and a so-called Certificate Sign Request (CSR) are generated locally. This CSR is manually signed by the broker operator, which allows the Bridgehead access to the network infrastructure.
All communication runs via Samply.Beam and is therefore end-to-end encrypted, but also signed. This allows the integrity and authenticity of the sender to be technically verified (which happens automatically both in the broker and at the recipients).
The connection to the broker is additionally secured using traditional TLS (transport encryption over https).
</details>
<details>
<summary><strong>Q: Are there any statistics on incoming traffic from the Bridgehead (what goes in and what goes out)?</strong></summary>
A: Incoming and outgoing traffic can only enter/leave the Bridgehead via a forward or reverse proxy, respectively. These components log all connections.
Statistical analysis is not currently being conducted, but is on the roadmap for some projects. We are also working on a dashboard for all tasks/responses delivered via Beam.
</details>
<details>
<summary><strong>Q: How is container access controlled, and what permission level is used?</strong></summary>
A: Currently, it is not possible to run the Bridgehead "out-of-the-box" as a rootless Docker Compose stack. The main reason is the operation of the reverse proxy, which binds to the privileged ports 80 (HTTP) and 443 (HTTPS).
Otherwise, there are no known technical obstacles, although we don't have concrete experience implementing this.
At the file system level, a "bridgehead" user is created during installation, which manages the configuration and Bridgehead folders.
</details>
<details>
<summary><strong>Q: Is a cloud installation (not a company-owned one, but an external service provider) possible?</strong></summary>
A: Technically, yes. This is primarily a data protection issue between the participant and their cloud provider.
The Bridgehead contains a data storage system that, during use, contains sensitive patient and sample data.
There are cloud providers with whom appropriately worded contracts can be concluded to make this possible.
Of course, the details must be discussed with the responsible data protection officer.
</details>
<details>
<summary><strong>Q: What needs to be considered regarding the Docker distribution/registry, and how is it used here?</strong></summary>
A: The Bridgehead images are located both in Docker Hub and mirrored in a registry operated by the DKFZ.
The latter is used by default, avoiding potential issues with Docker Hub URL activation or rate limits.
When using automatic updates (highly recommended), an hourly check is performed for:
- site configuration updates
- Bridgehead software updates
- container image updates
If updates are found, they are downloaded and applied.
See the first question for the control mechanism.
</details>
<details>
<summary><strong>Q: Is data only transferred one-way (Bridgehead/FHIR Store → GBN Node), or is two-way access necessary?</strong></summary>
A: By using Samply.Beam, only one outgoing connection to the broker is required at the network level (i.e., Bridgehead → Broker).
</details>
<details>
<summary><strong>Q: Are there already thoughts regarding data export from Centraxx to Bridgehead/DZPG Node?</strong></summary>
A: TransFAIR would be a good option for loading the data from the DIZ into the BK.
CentraXX has the FHIR export interface, which is expensive.
Our colleagues in Frankfurt and Mainz have already developed a data integration tool for CentraXX export—perhaps we could exchange ideas here.
</details>
## Troubleshooting
### Docker Daemon Proxy Configuration