Merge b78c11e into 7277181

docs/algorithms/index.rst

@@ -1,11 +1,11 @@
 .. _algorithm-docs:
 
-Algorithm Dev
-=============
+Algorithm Development
+=====================
 
 This section helps you to develop MPC and FL algorithms that are compatible
 with vantage6. You are **not** going to find a list of algorithms here or help
-on how to use them. In the :ref:`concepts` the basic concepts and interface
+on how to use them. In the :ref:`components` the basic concepts and interface
 between node and algorithm is explained. Then in the :ref:`algo-tutorial` a
 FL algorithm is build from scratch.
 

docs/conf.py

@@ -75,6 +75,7 @@
     # 'fixed_sidebar': True,
 }
 
+html_favicon = '_static/logo.png'
 
 # The master toctree document.
 master_doc = 'index'

docs/devops/index.rst

@@ -1,7 +1,7 @@
 .. _dev-docs:
 
-Dev community
-=============
+Developer community
+===================
 
 As an open-source platform, we welcome anyone who would like to contribute to
 the vantage6 code and/or documentation. The following sections are meant to

docs/index.rst

@@ -1,66 +1,23 @@
-
 .. include:: <isonum.txt>
+
 .. _introduction:
 
 Introduction
 ============
-This section will describe the community, the overall architecture of the
-platform and explains how this documentation space is organized.
-
-
-Overview
---------
-This documentation space consists of the following main sections:
-
-* **Introduction** |rarr| *You are here now*
-* :doc:`/user-documentation/index` |rarr| *Install and use vantage6-servers,
-  -nodes or -clients*
-* :doc:`/technical-documentation/index` (Under construction) |rarr|
-  *Implementation details of the vantage6 platform*
-* :doc:`/devops/index` |rarr| *How to collaborate on the development of the
-  vantage6 infrastructure*
-* :doc:`/algorithms/index` |rarr| *Develop algorithms that are compatible with
-  vantage6*
-* :doc:`/glossary` |rarr| *A dictionary of common terms used in these docs*
-* :doc:`/release_notes` |rarr| *Log of what has been released and when*
-
-
-Resources
----------
-
-**Documentation**
-
-* `docs.vantage6.ai <https://docs.vantage6.ai>`_ |rarr| *This documentation.*
-* `vantage6.ai <https://vantage6.ai>`_ |rarr| *vantage6 project website*
-* `Academic papers <https://vantage6.ai/vantage6/>`_ |rarr|
-  *Technical insights into vantage6*
-
-**Source code**
-
-* `vantage6 <https://github.com/vantage6/vantage6>`_ |rarr| *Contains all*
-  *components (and the python-client).*
-* `Planning <https://github.com/orgs/vantage6/projects>`_ |rarr| *Contains all
-  features, bugfixes and feature requests we are working on. To submit one
-  yourself, you can create a*
-  `new issue <https://github.com/vantage6/vantage6/issues>`_.
-
-**Community**
-
-* `Discord <https://discord.gg/yAyFf6Y>`_  |rarr| *Chat with the vantage6
-  community*
-* :ref:`Community meetings <Community Planning>` |rarr| *Bi-monthly developer
-  community meeting*
-
 
 What is vantage6?
 -----------------
 Vantage6 stands for pri\ **va**\ cy preservi\ **n**\ g
 federa\ **t**\ ed le\ **a**\ rnin\ **g** infrastructur\ **e** for
 \ **s**\ ecure \ **i**\ nsight e\ **x**\ change.
 
-Watch this `video <https://youtu.be/HVHvlkAeuD0>`_ for a quick introduction.
+.. raw:: html
 
-.. todo insert the video above directly into docs (requires sphinx extension)
+   <iframe width="750" height="420" src="https://youtube.com/embed/HVHvlkAeuD0"
+     frameborder="0"
+     allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
+     allowfullscreen>
+   </iframe>
 
 The project is inspired by the `Personal Health Train <https://pht.health-ri.nl/>`_
 (PHT) concept. In this analogy vantage6 is the *tracks* and *stations*.
@@ -91,56 +48,72 @@ aspects of federated learning.
    should not limit the use of relevant data.
 
 
-.. _architectureoverview:
+Overview of this documentation
+------------------------------
+
+This documentation space consists of the following main sections:
 
-Architecture
-------------
+* **Introduction** |rarr| *You are here now*
+* :doc:`/install/index` |rarr| *How to install vantage6 servers,
+  nodes and clients*
+* :doc:`/use/index` |rarr| *How to use vantage6 servers,
+  nodes and clients*
+* :doc:`/technical-documentation/index` (Under construction) |rarr|
+  *Implementation details of the vantage6 platform*
+* :doc:`/devops/index` |rarr| *How to collaborate on the development of the
+  vantage6 infrastructure*
+* :doc:`/algorithms/index` |rarr| *Develop algorithms that are compatible with
+  vantage6*
+* :doc:`/glossary` |rarr| *A dictionary of common terms used in these docs*
+* :doc:`/release_notes` |rarr| *Log of what has been released and when*
 
-In vantage6, a **client** can pose a question to the **server**, which is then
-delivered as an **algorithm** to the **node** (:numref:`architecture-figure`).
-When the algorithm completes, the node sends the results back to the client via
-the server. An algorithm may be enabled to communicate directly with twin
-algorithms running on other nodes.
 
-.. _architecture-figure:
-.. figure:: /images/architecture-overview.png
-   :alt: Architecture overview
-   :align: center
+Vantage6 resources
+------------------
 
-   Vantage6 has a client-server architecture. (A) The client is used by the
-   researcher to create computation requests. It is also used to manage users,
-   organizations and collaborations. (B) The server contains users,
-   organizations, collaborations, tasks and their results. (C) The nodes have
-   access to data and handle computation requests from the server.
+This is a - non-exhaustive - list of vantage6 resources.
 
-Conceptually, vantage6 consists of the following parts:
+**Documentation**
 
-* A (central) **server** that coordinates communication with clients and nodes.
-  The server is in charge of processing tasks as well as handling
-  administrative functions such as authentication and authorization.
-* One or more **node(s)** that have access to data and execute algorithms
-* **Users** (i.e. researchers or other applications) that request computations
-  from the nodes via the client
-* **Organizations** that are interested in collaborating. Each user belongs to
-  one of these organizations.
-* A **Docker registry** that functions as database of algorithms
+* `docs.vantage6.ai <https://docs.vantage6.ai>`_ |rarr| *This documentation.*
+* `vantage6.ai <https://vantage6.ai>`_ |rarr| *vantage6 project website*
+* `Academic papers <https://vantage6.ai/vantage6/>`_ |rarr|
+  *Technical insights into vantage6*
+
+**Source code**
+
+* `vantage6 <https://github.com/vantage6/vantage6>`_ |rarr| *Contains all*
+  *components (and the python-client).*
+* `Planning <https://github.com/orgs/vantage6/projects>`_ |rarr| *Contains all
+  features, bugfixes and feature requests we are working on. To submit one
+  yourself, you can create a*
+  `new issue <https://github.com/vantage6/vantage6/issues>`_.
+
+**Community**
+
+* `Discord <https://discord.gg/yAyFf6Y>`_  |rarr| *Chat with the vantage6
+  community*
+* :ref:`Community meetings <Community Planning>` |rarr| *Bi-monthly developer
+  community meeting*
 
-On a technical level, vantage6 may be seen as a container
-orchestration tool for privacy preserving analyses. It deploys a network of
-containerized applications that together ensure insights can be exchanged
-without sharing record-level data.
 
 -------------------------------------------------------------------------------
 
 Index
 =====
 
 .. toctree::
-   :numbered: 3
    :maxdepth: 4
 
    self
-   user-documentation/index
+   introduction/concepts
+
+.. toctree::
+   :numbered: 3
+   :maxdepth: 4
+
+   install/index
+   use/index
    algorithms/index
    devops/index
    glossary

docs/install/client.rst

@@ -0,0 +1,74 @@
+.. _client install:
+
+Client
+------
+
+We provide four ways in which you can interact with the server to manage
+your vantage6 resources: the :ref:`install_ui` (UI), the
+:ref:`Python client <python client library>`, the
+:ref:`R client <r client library>`, and the server API. Below are installation
+instructions for each of them.
+
+For most use cases, we recommend to use the UI (for anything except
+creating tasks - this is coming soon) and/or the Python Client. The latter
+covers the server functionality completely, but is more convenient for most
+users than sending HTTP requests directly to the API.
+
+.. warning::
+    Depending on your algorithm it *may* be required to use a specific
+    language to post a task and retrieve the results. This could happen when
+    the output of an algorithm contains a language specific datatype and or
+    serialization.
+
+.. _install_ui:
+
+User interface
+^^^^^^^^^^^^^^
+
+The UI is available as a website, so you don't have to install anything! Just
+go to the webpage and login with your user account. If you are using the
+Petronas server, simply go to https://portal.petronas.vantage6.ai.
+
+If you are a server admin and want to set up a user interface, see :ref:`UI`.
+
+Python client library
+^^^^^^^^^^^^^^^^^^^^^
+
+Before you install the Python client, we check the version of the server you
+are going to interact with first. If you are using an existing server, check
+``https://<server_url>/version`` (e.g. `https://petronas.vantage6.ai/version`
+or `http://localhost:5000/api/version`) to find its version.
+
+Then you can install the ``vantage6-client`` with:
+
+::
+
+   pip install vantage6==<version>
+
+where you add the version you want to install. You may also leave out
+the version to install the most recent version.
+
+.. _r client install:
+
+R client library
+^^^^^^^^^^^^^^^^
+
+The R client currently only supports creating tasks and retrieving their
+results. It can not (yet) be used to manage resources, such as creating
+and deleting users and organizations.
+
+You can install the R client by running:
+
+.. code:: r
+
+   devtools::install_github('IKNL/vtg', subdir='src')
+
+
+Server API
+^^^^^^^^^^
+
+The API can be called via HTTP requests from a programming language of your
+choice. Hence, what you need to install, depends on you!
+
+You can explore how to use the server API on ``https://<serverdomain>/apidocs``
+(e.g. https://petronas.vantage6.ai/apidocs for our Petronas server).

docs/install/index.rst

@@ -0,0 +1,22 @@
+.. include:: <isonum.txt>
+
+.. _install_vantage6:
+
+Installation
+============
+
+The vantage6 framework consists of several components that
+should be installed. Which component(s) you need depends on your use case. For
+example, if you only need to communicate to an existing vantage6 server, you
+don't have to install a server.
+
+We will first detail the requirements for installing a node and/or server, and
+then explain the installation process per component.
+
+.. toctree::
+    :maxdepth: 3
+
+    requirements
+    client
+    node
+    server

docs/install/node.rst

@@ -0,0 +1,17 @@
+
+.. _install-node:
+
+Node
+----
+
+To install the **vantage6-node** make sure you have met the
+:ref:`requirements <requirements>`. Then install the latest version:
+
+::
+
+   pip install vantage6
+
+This will install the CLI in order to configure, start and stop the node. The
+node software itself will be downloaded when you start the node for the first
+time. See :ref:`here <use-node>` for more details on how to do that.
+