Skip to content

feat: first version of demo instance chapter #106

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
marlenamey wants to merge 1 commit into
base: master
Choose a base branch
from
Open

feat: first version of demo instance chapter #106

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 20 additions & 16 deletions src/.vitepress/routes/sidebar/user.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,21 +15,21 @@ export const userRoutes = [
text: 'Analysis Coding',
collapsed: true,
items: [
{text: 'Introduction', link: '/analysis-coding'},
{ text: 'Introduction', link: '/analysis-coding' },
{
text: 'Examples',
collapsed: true,
items: [
{text: 'Aggregation with fedstats', link: '/coding_examples/survival-regression'},
{text: 'Basic VCF QC', link: '/coding_examples/vcf-qc'},
{text: 'CLI Tools FastQC', link: '/coding_examples/cli-fastqc'},
{text: 'Deep Learning image classification', link: '/coding_examples/deep-learning-image-classifier'},
{text: 'Differential Privacy', link: '/coding_examples/differential-privacy-mvp'},
{text: 'Fedstats GLM', link: '/coding_examples/fedstats-logistic-regression'},
{text: 'Federated Logistic Regression', link: '/coding_examples/federated-logistic-regression'},
{text: 'GeMTeX text scores', link: '/coding_examples/gemtex-text-score-example'},
{text: 'Long COVID (PASC) Analysis', link: '/coding_examples/pasc-long-covid-analysis'},
{text: 'PPRL', link: '/coding_examples/record_linkage'},
{ text: 'Aggregation with fedstats', link: '/coding_examples/survival-regression' },
{ text: 'Basic VCF QC', link: '/coding_examples/vcf-qc' },
{ text: 'CLI Tools FastQC', link: '/coding_examples/cli-fastqc' },
{ text: 'Deep Learning image classification', link: '/coding_examples/deep-learning-image-classifier' },
{ text: 'Differential Privacy', link: '/coding_examples/differential-privacy-mvp' },
{ text: 'Fedstats GLM', link: '/coding_examples/fedstats-logistic-regression' },
{ text: 'Federated Logistic Regression', link: '/coding_examples/federated-logistic-regression' },
{ text: 'GeMTeX text scores', link: '/coding_examples/gemtex-text-score-example' },
{ text: 'Long COVID (PASC) Analysis', link: '/coding_examples/pasc-long-covid-analysis' },
{ text: 'PPRL', link: '/coding_examples/record_linkage' },
]
},
]
Expand All @@ -39,19 +39,19 @@ export const userRoutes = [
text: 'Local Testing',
collapsed: true,
items: [
{text: 'Introduction', link: '/local-testing'},
{ text: 'Introduction', link: '/local-testing' },
{
text: 'Examples',
collapsed: true,
items: [
{text: 'Logistic Regression', link: '/testing_examples/local-testing-logistic-regression-example'},
{text: 'Differential Privacy', link: '/testing_examples/local-testing-dp-example'},
{text: 'Long COVID (PASC) Analysis', link: '/testing_examples/local-testing-pasc-example'},
{ text: 'Logistic Regression', link: '/testing_examples/local-testing-logistic-regression-example' },
{ text: 'Differential Privacy', link: '/testing_examples/local-testing-dp-example' },
{ text: 'Long COVID (PASC) Analysis', link: '/testing_examples/local-testing-pasc-example' },
]
},
]
},
{text: 'FHIR Queries', link: '/fhir-query'},
{ text: 'FHIR Queries', link: '/fhir-query' },
// {text: 'Homomorphic Encryption', link: '/homomorphic-encryption'},
]
},
Expand All @@ -70,4 +70,8 @@ export const userRoutes = [
},
]
},
{
text: 'Demo Instance',
link: '/demo'
},
]
20 changes: 13 additions & 7 deletions src/guide/deployment/node-installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -281,6 +281,12 @@ to properly import the configuration. This can cause the `helm install` to hang
is deployed and verified, so please have patience during this step and do not prematurely cancel the command.
:::

### Verify Installation

To confirm that the deployment was successful and the node can communicate with the Hub, you can run a demo
analysis. This involves connecting a datastore, creating a project in the Hub, and executing a predefined demo
analysis. See the [Demo Instance guide](../user/demo) for full step-by-step instructions.

## Proxies

If your server is behind a proxy i.e. all traffic is routed through a specific address and/or port, then the FLAME Node
Expand Down Expand Up @@ -384,9 +390,9 @@ Your `my-values.yaml` can then be used during deployment to provide the certific

## Storage Class Definitions

Because several services in this helm chart need to store long-term data, they will request storage space via a
persistent volume claim (PVC) using the default storage class defined in your kubernetes cluster. If you want to
specify which storage class these services use (e.g. longhorn), here is a minimal example for your `my-values.yaml`
Because several services in this helm chart need to store long-term data, they will request storage space via a
persistent volume claim (PVC) using the default storage class defined in your kubernetes cluster. If you want to
specify which storage class these services use (e.g. longhorn), here is a minimal example for your `my-values.yaml`
file:

```yaml
Expand Down Expand Up @@ -439,9 +445,9 @@ dataStore:
```

### Creating a Storage Class
There are multiple reasons why you may want to create a new storage class in your kubernetes cluster such as
delineating fast (SSD) vs slow (HDD) storage pools, different provisioners or binding modes, or for implementing
encryption. For more information on how to set up a specialized storage class on your cluster, see the
There are multiple reasons why you may want to create a new storage class in your kubernetes cluster such as
delineating fast (SSD) vs slow (HDD) storage pools, different provisioners or binding modes, or for implementing
encryption. For more information on how to set up a specialized storage class on your cluster, see the
[official kubernetes documentation](https://kubernetes.io/docs/concepts/storage/storage-classes/)

## Deploying without a Domain Name
Expand Down Expand Up @@ -572,4 +578,4 @@ dataStore:
secret:
adminUser: "<username>"
adminPassword: "<password>"
```
```
91 changes: 91 additions & 0 deletions src/guide/user/demo.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
<!---
How to write block comments [you can do anything you want in here]
--->

[comment]: # (How to write line comments [must not contain brackets])

[comment]: # "How to write line comments [must not contain quotations]"

[//]: # (How to write line comments [must not contain brackets])

[//]: # "How to write line comments [must not contain quotations]"

[comment]: <> (How to write line comments [must not contain brackets])

[comment]: <> "How to write line comments [must not contain quotations]"

[//]: <> (How to write line comments [must not contain brackets])

[//]: <> "How to write line comments [must not contain quotations]"

# Demo Instance

## Overview

This guide explains how analysts can execute analyses on FLAME. It serves as a starting point and provides an overview of the complete workflow, linking to the detailed documentation for each individual step.

Two common use cases are covered:

- Running the existing demo analysis [HALTA](https://github.com/PrivateAIM/Herrsching2026) to become familiar with the platform and verify that the environment is working correctly.
- Developing and executing your own analysis, using either the provided demo code as a starting point or your own analysis implementation.

### Scope

This guide covers the complete workflow required to prepare and execute an analysis on the demo instance. It explains how to:

- create and configure a project
- upload data and make it available in a data store
- connect the data store to a FLAME node
- execute an existing demo analysis
- develop and run your own analysis

Where appropriate, references to dedicated documentation pages are provided for more detailed explanations of individual steps.

### Goal

After completing this guide, you should be able to make data available for analysis and successfully execute either a provided demo analysis or your own analysis on the FLAME platform.

## Preparation

### 1. Create a Project in the Hub

To run an analysis, a project must first be created in the Hub. A project defines the scope of the analysis,
including the target nodes, the requested data, and the images to be used. Creating a project is described in detail [here](./project).

@coderabbitai coderabbitai Bot Jul 24, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Replace “here” with descriptive link labels.

Use labels such as “Create a project,” “Set up a data-store bucket,” “Manage data-store connections,” and “Create an analysis” so links remain understandable out of context.

Also applies to: 60-60, 72-72, 79-79

🧰 Tools
🪛 markdownlint-cli2 (0.23.0)

[warning] 53-53: Link text should be descriptive

(MD059, descriptive-link-text)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/guide/user/demo.md` at line 53, Replace the generic “here” link labels in
the demo guide, including the references at the project, data-store bucket,
data-store connections, and analysis sections, with descriptive labels such as
“Create a project,” “Set up a data-store bucket,” “Manage data-store
connections,” and “Create an analysis,” while preserving the existing
destinations.

Source: Linters/SAST tools



### 2. Upload Data to the Data Store

To run an analysis on data, the data first needs to be made available in the corresponding node's data store. Each node has its own data store, in which a dedicated bucket can be created for each project. The required data can then be uploaded to the project-specific bucket.

The setup of a data store bucket is described in detail [here](../admin/bucket-setup-for-data-store).

#### Demo Data

The data for the existing demo analysis [HALTA](https://github.com/PrivateAIM/Herrsching2026) can be found [here for Node 1](https://github.com/PrivateAIM/Herrsching2026/blob/master/data/node1/synthetic_eucare_1_labeled.csv) and [here for Node 2](https://github.com/PrivateAIM/Herrsching2026/blob/master/data/node2/synthetic_eucare_2_labeled.csv).

#### Synthetic Data

If you do not have access to real data, you can create your own synthetic dataset and use it to test your analysis.

### 3. Connect the Data Store to the Node

To enable an analysis to access the required data, the data store must be connected to the corresponding node. The process of connecting a data store to a node is described in detail [here](../admin/data-store-management).


## Running Analyses

Once the project has been created, the data uploaded to the data store, and the data store connected to the node,
an analysis can be created within the project. Creating an analysis involves selecting the analysis code, the
target nodes, and the entrypoint for the analysis, and is described in detail [here](./analysis).

[//]: # (TODO: update analysis.md, its content is outdated)
Comment on lines +79 to +81

@coderabbitai coderabbitai Bot Jul 24, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Do not ship a known-outdated prerequisite link.

The workflow directs users to analysis.md while explicitly stating that its content is outdated. Update that page or provide the current analysis-creation steps here before publishing the end-to-end guide.

🧰 Tools
🪛 markdownlint-cli2 (0.23.0)

[warning] 79-79: Link text should be descriptive

(MD059, descriptive-link-text)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/guide/user/demo.md` around lines 79 - 81, Resolve the outdated analysis
prerequisite referenced by the guide: either update the linked analysis
documentation at the `./analysis` target with current content, or replace the
link with accurate analysis-creation steps in `demo.md`; remove the TODO
indicating known-stale documentation before publishing.


### Run the Demo Analysis

The script for the existing demo analysis [HALTA](https://github.com/PrivateAIM/Herrsching2026) is available
[on GitHub](https://github.com/PrivateAIM/Herrsching2026/blob/master/analysis/analysis.py) and can be used to run
the demo analysis on the previously uploaded demo data.

### Create Your Own Analysis

See [Analysis Coding](./analysis-coding) for instructions on developing your own analysis.
Loading