Update chapter 4 and 6

episodes/chapter4.md

@@ -1,13 +1,11 @@
 ---
 title: "Managing vantage6 server via the user interface"
 teaching: 2
-exercises: 3
+exercises: 2
 ---
 
 :::::::::::::::::::::::::::::::::::::: questions
 
-- What are the administrative entities in vantage6?
-- What is the relation between the entities in vantage6?
 - What is the permission system in vantage6?
 - What are the default roles in vantage6?
 - How to create a new organization using vantage6 user interface (UI)?
@@ -18,78 +16,18 @@ exercises: 3
 
 ::::::::::::::::::::::::::::::::::::: objectives
 
-- Understand the types of administrative entities in vantage6
-- Understand the relation between the administrative entities of vantage6
 - Understand the permission system of vantage6
 - Understand the default roles in vantage6
 - Be able to create a new organization using the vantage6 UI
 - Be able to create a new user using the vantage6 UI
 - Be able to create a new collaboration using the vantage6 UI
-- Be able to reset an api key for a node
-
-::::::::::::::::::::::::::::::::::::::::::::::::
-
-
-## Vantage6 entities and their relations
-
-There are several entities in vantage6, such as users, organizations, tasks, etc. These entities are created by users that have sufficient permission to do so and are stored in a database that is managed by the central server.
-
-The administrative entities in vantage6 are:
-
-- **User**: a person who can perform certain actions in vantage6.
-    - A user can only belong to one **organization**.
-    - A user can have multiple **roles** and can be assigned with extra permissions not covered by the roles.
-    - A user can create **tasks** for one or more **organizations** within a **collaboration**.
-- **Organization**: an orgarnization to which users belong
-    - An organization can have zero and more **users**.
-    - An organization can have multiple **nodes**.
-- **Collaboration**: a collection of one or more **organizations**.
-    - In a specific **collaboration**, each participating **organization** needs one **node** to compute **tasks**; In another **collaboration**, the same **organization** must have a separate **node** for this **collaboration**.
-    - A collaboration can contain zero or more **studies**.
-    - A **study** is a subset of organizations from the collaboration that are involved in a specific research question. By setting up studies, it can be easier to send tasks to a subset of the organizations in a collaboration and to keep track of the results of these analyses.
-- **Role**: a collection of rules that define the permissions of a user.
-    - A user can have multiple roles.
-    - The permissions of the user are defined by the assigned **rules**.
-    - **Rules** define what each entity is allowed to do, based on the operation (view, create, edit, delete, send, receive), the scope (own,  organization, collaboration, global), and the resource (e.g. users, orgarnizations).
-- **Node**: an application that can execute **tasks**.
-- **Task**: a task that is executed by one or more **nodes**.
-    - A task should use an algorithm run for each organization involved in the task. The results are part of such an algorithm run.
-    - A task can be part of a **study** or a **collaboration**.
-
-The following diagram is simplified relations between these entities. A `1-n` relationship means that the entity on the left side of the relationship can have multiple entities on the right side. For instance, a single organization can have multiple vantage6 users, but a single user always belongs to one organization. There is one `0-n` relationship between roles and organizations, since a role can be coupled to an organization, but it doesn’t have to be. An `n-n` relationship is a many-to-many relationship: for instance, a collaboration can contain multiple organizations, and an organization can participate in multiple collaborations.
-
-![vantage6 relations between entities](fig/v6_entities.png)
-
-### Where are the entities in the UI?
-
-After logging in to the vantage6 UI, you will see the start page.
-
-![vantage6 UI start page](fig/ui_start_page.png)
-
-There are some collbarations displayed on the start page. Clicking one of the collaborations will show the tasks of that collaboration.
-
-![vantage6 UI tasks page](fig/ui_task_page.png)
-
-The start page also contains a button `Administration` in the top right corner. Clicking on this button will redirect you to the administration page.
-
-In the administration page, you can manage the entities of vantage6. The entities are divided into tabs: `Organizations`, `Collaborations`, `Roles`, `Users`, and `Nodes`. You can click on an entity to see more details or to edit the entity. We will get back to this later in more detail.
-
-![vantage6 UI administration page](fig/ui_admin_page.png)
-
-::::::::::::::::::::::::::::::::::::: challenge
-
-## Challenge 1: Get familiar with the vantage6 UI
-
-Log in to the vantage6 UI and navigate to the `Administration` page. Familiarize yourself with the entities in the administration page.
-
-Can you find the `Organizations`, `Collaborations`, `Roles`, `Users`, and `Nodes` tabs?
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
 
 ## Vantage6 permission system
 
-vantage6 uses a permission system to control who can do what in the system. The permission system is based on **roles**, which are collections of rules that define the permissions of a user. A user can have multiple roles, and the permissions of the user are defined by the assigned **rules**.
+Vantage6 uses a permission system to control who can do what in the system. The permission system is based on **roles**, which are collections of rules that define the permissions of a user. A user can have multiple roles, and the permissions of the user are defined by the assigned **rules**.
 
 The permission rules define what each entity is allowed to do, based on the operation (view, create, edit, delete, send, receive), the scope (own,  organization, collaboration, global), and the resource (e.g. users, orgarnizations). Users can be assigned anywhere between zero and all of these permission rules. For example, having the rules with `create` in the scope `organization` for the resource `users` means that the user can create users for the organization they belong to.
 
@@ -111,13 +49,13 @@ The permission structure allows for a lot of flexibility, but it can be complex
 
 ::::::::::::::::::::::::::::::::::::: challenge
 
-## Challenge 2: What can you do in vantage6?
+## Challenge 1: What can you do in vantage6?
 
 Go the administration page in the vantage6 UI, check the permissions that you have, and answer the following questions:
 
 1. What is your role in vantage6?
 2. Do you have the permissions to create a new organization, a new user or a new collaboration?
-3. Do you have the permission to remove an existing organization, a user, or a collboration?
+3. Do you have the permission to remove an existing organization, a user, or a collaboration?
 
 :::::::::::::::::::::::: solution
 
@@ -140,7 +78,7 @@ Note that the role `Collaboration Admin` does not have the permission to create
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
 
-In this section, we will go through the steps to create a new organization, a new user, a new collaboration and reset an api key for a node using the vantage6 UI.
+In this section, we will go through the steps to create a new organization, a new user and a new collaboration using the vantage6 UI.
 
 First you need to log in to the vantage6 UI, and then go to the `Administration` page. You can find the `Administration` button in the top right corner of the start page.
 
@@ -182,7 +120,7 @@ A collaboration is a collection of one or more organizations. Let's create a new
 ![Create a new collaboration](fig/create_collab_01.png)
 
 4. Click on the `Submit` button to create the new collaboration.
-    * After submitting the form, you may see a dialog box to ask you to download the API key (on MacOS) or a dialog points out that the API key has been downloaded (on Windows). The API key is used to authenticate the nodes in the collaboration. Later we will see how to reset the API key for a node.
+    * After submitting the form, you may see a dialog box to ask you to download the API key (on MacOS) or a dialog points out that the API key has been downloaded (on Windows). The API key is used to authenticate the nodes in the collaboration.
 
 ![Download API keys](fig/create_collab_02.png)
 
@@ -194,53 +132,35 @@ You will see a message:
 >
 > Please distribute each of these keys privately to each of the organizations. Note that they may reset their API key so that no-one but them knows it.
 
-5. After creating the collaboration, you can see the details of the collaboration by clicking on the specific collaboration listed in the `Collaborations` tab.
+You will need the API keys when you run the nodes to authenticate with the vantage6 server. We will discuss this in [the chapter of setting up a vantage6 node](./chapter6.md).
+
+1. After creating the collaboration, you can see the details of the collaboration by clicking on the specific collaboration listed in the `Collaborations` tab.
     * You will see what organizations are participating in the collaboration.
     * You will see the nodes of the organizations that are registered in the collaboration. If no nodes are registered, you can register them manually by clicking the `Register missing nodes` button.
     * You can also see the algorithm store available for the collaboration. You can add a algorithm store for the collaboration by clicking the `Add algorithm store` button.
     * You can also see the studies of the collaboration. You can add a study by clicking the `Add study` button.
 
 ![Collaboration details](fig/create_collab_03.png)
 
-### Reset API key for a node
-If you want to reset the API key for a node, you can do so by following these steps:
-
-1. Click on the `Nodes` tab in the administration page.
-2. Click on the tab of the node you want to reset the API key for in the list of nodes.
-
-![Reset API key for a node](fig/reset_api_key_01.png)
-
-3. Click on the `Reset API key` button.
-    * You will see a dialog box to ask you to download the new API key.
-
-![Download new API key](fig/reset_api_key_02.png)
-
-You will see a message:
-
-> API key download
->
-> Your API key has been reset. Please read your new key in the file that has been downloaded.
-
-At this point, put the new API key in your node configuration file and restart the node to connect to the server again.
 
 ::::::::::::::::::::::::::::::::::::: challenge
 
-## Challenge 3: Manage vantage6 project using the UI
+## Challenge 2: Manage vantage6 project using the UI
 
-Go the administration page in the vantage6 UI and try to create a new organization, a new user, and a new collaboration. Also, try to reset the API key for a node.
+Go to the administration page in the vantage6 UI, and do the following:
 
-1. Can you create a new organization, a new user, and a new collaboration?
-2. Can you reset the API key for a node?
-3. Which steps are challenging for you?
+1. Create a new organization
+2. Create a new user
+3. Create a new collaboration
 
-::::::::::::::::::::::::::::::::::::::::::::::::
+Which steps are challenging for you?
 
+::::::::::::::::::::::::::::::::::::::::::::::::
 
 ::::::::::::::::::::::::::::::::::::: keypoints
 
-- Vantage6 entities are `Users`, `Organizations`, `Collaborations`, `Roles`, `Nodes`, and `Tasks`.
 - Vantage6 uses a permission system to control who can do what in the system.
 - Vantage6 has default roles like  `Root`, `Collaboration Admin`, `Organization Admin`, `Researcher`, and `Viewer`.
-- Vantage6 UI can be used to manage the entities of vantage6, like creating a new organization, a new user, a new collaboration, and resetting an api key for a node.
+- Vantage6 UI can be used to manage the entities of vantage6, like creating or deleting an organization, a user, or a collaboration.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::

episodes/chapter6.md

@@ -1,7 +1,7 @@
 ---
 title: "Setting up a vantage6 node"
 teaching: 1
-exercises: 4
+exercises: 3
 ---
 
 :::::::::::::::::::::::::::::::::::::: questions
@@ -10,7 +10,7 @@ exercises: 4
 - How to install vantage6 command line interface?
 - What are the commands available in the vantage6 CLI?
 - How to set up a new vantage6 node?
-- How to update an API key for a node?
+- How to reset and update an API key for a node?
 
 :::::::::::::::::::::::::::::::::::::::::::::::::
 
@@ -19,7 +19,7 @@ exercises: 4
 - Understand the requirements for setting up vantage6 node
 - Understand the basic `v6` commands
 - Be able to create a new vantage6 node using `v6` commands
-- Be able to update an API key for a node
+- Be able to reset and update an API key for a node
 - Be able to observe the logs of vantage6 node
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
@@ -52,7 +52,7 @@ Even though a vantage6 node can be installed and run on Linux, Windows and Mac,
 
 The following software must be installed before installing the vantage6 node:
 
-- Operating system: Ubuntu 18.04+ , MacOS Big Sur+, or Windows 10+
+- Recommended Operating system: Ubuntu 20.04+, MacOS Big Sur+, or Windows 10+
 - Python
     - Python v3.10 for vantage6 version 3.8.0 or higher
     - Python v3.7 for other lower versions of vantage6
@@ -95,53 +95,6 @@ v6 --help
 If the installation is successful, it will print out a message explaining the CLI usage.
 
 
-::::::::::::::::::::::::::::::::::::: challenge
-
-## Challenge 1: Install vantage6 CLI
-
-Check the hardware and software requirements and install the vantage6 CLI package in your Python environment.
-
-Make sure you create a new virtual or conda environment for vantage6 CLI installation.
-
-Run the command `v6 --help` to verify the installation. What are the available commands?
-
-::: solution
-
-If the vantage6 CLI has been correctly installed, by running:
-
-```bash
-v6 --help
-```
-
-the following messages will be printed:
-
-```bash
-
-Usage: v6 [OPTIONS] COMMAND [ARGS]...
-
-  The `v6` command line interface allows you to manage your vantage6
-  infrastructure.
-
-  It provides a number of subcommands to help you with this task.
-
-Options:
-  --help  Show this message and exit.
-
-Commands:
-  algorithm        Manage your vantage6 algorithms.
-  algorithm-store  Manage your vantage6 algorithm store server instances.
-  dev              Quickly manage a test network with a server and...
-  node             Manage your vantage6 node instances.
-  server           Manage your vantage6 server instances.
-  test             Execute tests on your vantage6 infrastructure.
-```
-You can see that vantage6 CLI provides commands to manage the server (`v6 server`), node (`v6 node`) and algorithms (`v6 algorithm`) and algorithm store (`algorithm-store`).
-
-:::
-
-::::::::::::::::::::::::::::::::::::::::::::::::
-
-
 ## `v6 node` commands
 
 The vantage6 CLI provides the `v6 node` command to manage the vantage6 node instances.
@@ -249,10 +202,14 @@ In the printed message, you will see not only the path of the configuration file
 
 ::::::::::::::::::::::::::::::::::::: challenge
 
-## Challenge 2: Create a new node configuration
+## Challenge 1: Create a new node configuration
 
 1. Create a new node configuration using the `v6 node new` command.
 2. Find the path to the configuration file using the `v6 node files` command. Open the configuration file with a text editor and check the configuration options. Are they correct?
+3. Open your configuration file, do the following:
+    - add a new database in the format of `excel`,
+    - enable the encryption,
+    - find the missing options in your file by comparing with the option template in the [vantage6 documentation](https://docs.vantage6.ai/en/main/node/configure.html#all-configuration-options).
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
@@ -399,7 +356,7 @@ From there, you can see the running status of the node, the connection to the se
 
 ::::::::::::::::::::::::::::::::::::: challenge
 
-## Challenge 3: Start a node and watch the logs
+## Challenge 2: Start a node and watch the logs
 
 1. Start the node you just created using the `v6 node start` command.
 2. Watch the logs of the node using the `v6 node attach --name xxx` command. Observe the logs and see if the node is running correctly.
@@ -456,9 +413,33 @@ after you choose the node, it will print out the following messages:
 
 ## Update the API key of your node
 
-If you get a new API key for a node from the server administrator, or you reset the API key in the vantage6 UI, you need to update the API key in the node configuration file.
+### Reset API key for a node via the vantage6 UI
+
+If you want to reset the API key for a node, you can do so by following these steps:
 
-For that, you can run the command:
+1. Login to the vantage6 UI.
+2. Click on the `Nodes` tab in the administration page.
+3. Click on the tab of the node you want to reset the API key for in the list of nodes.
+
+![Reset API key for a node](fig/reset_api_key_01.png)
+
+4. Click on the `Reset API key` button.
+    * You may see a dialog box asking you to download the new API key.
+
+![Download new API key](fig/reset_api_key_02.png)
+
+You will see a message:
+
+> API key download
+>
+> Your API key has been reset. Please read your new key in the file that has been downloaded.
+
+You can open the downloaded text file to copy the new API key. Next, you'll use it to update your node configuration.
+
+
+### Update API key in the node configuration file
+
+You can use v6 CLI to update the API key of a node. For that, you can run the command:
 
 ```bash
 v6 node set-api-key
@@ -473,7 +454,7 @@ then it will ask you which node you want to update the API key of:
    node3
 ```
 
-after you choose the node, it will ask you to enter the new API key:
+after you choose the node, it will ask you to enter the new API key, then you can paste the new API key you just copied from the downloaded file:
 
 ```bash
 ? Select the configuration you want to use: node1
@@ -512,22 +493,23 @@ When you finish the process, the node configuration file will be updated with th
 
 To make the new API key effective, you need to restart the node by running the command `v6 node stop` and then `v6 node start`.
 
-
 ::::::::::::::::::::::::::::::::::::: challenge
 
-## Challenge 4: Update the API key of a node
+## Challenge 3: Update the API key of a node
 
-1. How do you update the API key of a node? Try to update the API key of the node you just created, without using the `v6 node set-api-key` command.
-2. How do you make sure the new API key is effective?
+1. Reset the API key of the node you just created in the vantage6 UI
+2. Update the API key of the node you just created, without using the `v6 node set-api-key` command.
+3. How do you make sure the new API key is effective?
 
 ::: solution
-1. We can update the API key in the configuration file:
+1. You can go to the `Nodes` tab in the administration page, then click on the tab of the node you want to reset the API key for, and click on the `Reset API key` button.
+2. We can update the API key in the configuration file:
   - Run the `v6 node files` command to locate the configuration file.
   - Open the configuration file and write the new API key in the `api_key` field.
   - Stop the node with the `v6 node stop` command.
   - Restart the node with the `v6 node start` command.
 
-2. In order to verify the effectiveness of the API key change, we can restart the node with active logging:
+3. In order to verify the effectiveness of the API key change, we can restart the node with active logging:
 ```bash
 v6 node start --attach
 ```