From 4580db4f81d27ca531139bb1646d809fe394b0e5 Mon Sep 17 00:00:00 2001 From: marlenamey Date: Fri, 24 Jul 2026 15:37:19 +0200 Subject: [PATCH] feat: first version of demo instance chapter --- src/.vitepress/routes/sidebar/user.ts | 36 +++++---- src/guide/deployment/node-installation.md | 20 +++-- src/guide/user/demo.md | 91 +++++++++++++++++++++++ 3 files changed, 124 insertions(+), 23 deletions(-) create mode 100644 src/guide/user/demo.md diff --git a/src/.vitepress/routes/sidebar/user.ts b/src/.vitepress/routes/sidebar/user.ts index 9fbd6bb..e32e715 100644 --- a/src/.vitepress/routes/sidebar/user.ts +++ b/src/.vitepress/routes/sidebar/user.ts @@ -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' }, ] }, ] @@ -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'}, ] }, @@ -70,4 +70,8 @@ export const userRoutes = [ }, ] }, + { + text: 'Demo Instance', + link: '/demo' + }, ] diff --git a/src/guide/deployment/node-installation.md b/src/guide/deployment/node-installation.md index a4eadaf..5a1866d 100644 --- a/src/guide/deployment/node-installation.md +++ b/src/guide/deployment/node-installation.md @@ -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 @@ -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 @@ -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 @@ -572,4 +578,4 @@ dataStore: secret: adminUser: "" adminPassword: "" -``` +``` \ No newline at end of file diff --git a/src/guide/user/demo.md b/src/guide/user/demo.md new file mode 100644 index 0000000..674c6b7 --- /dev/null +++ b/src/guide/user/demo.md @@ -0,0 +1,91 @@ + + +[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). + + +### 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) + +### 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. \ No newline at end of file