Update docs (WIP)

VODAN-Tech · Jul 7, 2020 · c7827a6 · c7827a6
1 parent 5abe95e
commit c7827a6
Show file tree

Hide file tree

Showing 9 changed files with 133 additions and 6 deletions.
diff --git a/docs/_static/style.css b/docs/_static/style.css
@@ -0,0 +1,3 @@
+.wy-side-nav-search {
+  background-color: #EDEDED;
+}
diff --git a/docs/_static/vodan-logo.png b/docs/_static/vodan-logo.png
diff --git a/docs/about/about.rst b/docs/about/about.rst
@@ -10,10 +10,10 @@ What is VODAN in a Box?
 The toolset can be deployed wherever the user wants. It can be deployed in a cloud provider, in a server or on a local machine. Naturally, the first two options can be made accessible anywhere on the Web while the third option is normally for testing and demonstration purposes only. This deployment freedom provides flexibility for users who want **ViaB** the (meta)data to be stored locally (e.g., in a given hospital), nationally or internationally.
 
 What is in the "box"?
-----------------------------------------------
+---------------------
 
 **VODAN in a Box** is composed of:
 
 - Data Stewardship Wizard (DSW) - to capture and store data based on WHO's COVID-19 CRF;
 - FAIR Data Point (FDP) - to publish metadata about the COVID-19 CRF dataset and other pandemic-related content;
-- WHO COVID-19 Rapid Version CRF Semantic Data Model - this semantic data model has been embedded in DSW to provide semantically-rich RDF export to the data entered with the DSW.
+- WHO COVID-19 Rapid Version CRF Semantic Data Model - this semantic data model has been embedded in DSW to provide semantically-rich RDF export to the data entered with the DSW.
diff --git a/docs/about/components.rst b/docs/about/components.rst
@@ -0,0 +1,17 @@
+**********
+Components
+**********
+
+VODAN-in-a-Box consists of two significant services:
+
+- `Data Stewardship Wizard (DSW) <https://ds-wizard.org>`_ adjusted to serve as Wizard for filling and maintaining electronic case report forms (eCRF),
+- `FAIR Data Point (FDP) <https://github.com/FAIRDataTeam/FAIRDataPoint>`_ to maintain metadata about eCRFs created in DSW.
+
+To support it, there are other services included:
+
+- BlazeGraph triple store for FDP and optionally also to store eCRFs,
+- MongoDB used by both DSW and FDP,
+- JSON server providing controlled vocabulary for filling answers,
+- submission service that handles storing eCRFs in triple store and updating metadata in FDP,
+- RabbitMQ for queueing generation of an eCRF to a RDF document using DSW document worker,
+- (optionally) Nginx proxy for :ref:`production-deployment`.
diff --git a/docs/about/usagescenarios.rst → docs/about/usage-scenarios.rst b/docs/about/usagescenarios.rst → docs/about/usage-scenarios.rst
@@ -11,14 +11,41 @@ In this scenario, only the VODAN DSW and its COVID-19 semantic data model are us
 
 Normally, this scenario is indicated for the cases where metadata about the data does not need to be published.
 
+Those use cases are require user to be logged in in VODAN DSW:
+
+Create eCRF
+~~~~~~~~~~~
+
+1. Select :guilabel:`CRFs` from the left menu
+2. Press :guilabel:`Create` button
+3. Fill-in identifier and press :guilabel:`Save` button
+4. Fill CRF with data you have, :guilabel:`Save` or :guilabel:`Discard` changes accordingly
+
+Update eCRF
+~~~~~~~~~~~
+
+1. Select :guilabel:`CRFs` from the left menu
+2. Find by name the CRF you want to edit
+3. Fill CRF with new data you have, :guilabel:`Save` or :guilabel:`Discard` changes accordingly
+
+Submit eCRF
+~~~~~~~~~~~
+
+1. Open CRF you want to submit
+2. Press :guilabel:`Create Report`
+3. Press :guilabel:`Create` (optionally, you can name the report, e.g. "My report - v0.1")
+4. Press three dots on the right for the new report and press :guilabel:`Submit`
+5. Select the triple store you want to use and press :guilabel:`Submit`
+
+
 Metadata publication only
----------------
+-------------------------
 
 In this scenario, only the VODAN FDP is used to publish the pandemic-related content. This option is indicated for the cases where data have already been captured and only the FAIR metadata about them need to be published.
 
 Data could have been made available from other CRF-entry tools and extracted directly from databases of information systems such as electronic health record systems.
 
 Data-entry and metadata publication (complete package)
----------------
+------------------------------------------------------
 
-In this scenario, the whole **VODAN in a Box** is used, covering the data capture, semantic data generation and metadata publishing. 
+In this scenario, the whole **VODAN in a Box** is used, covering the data capture, semantic data generation and metadata publishing. 
diff --git a/docs/conf.py b/docs/conf.py
@@ -57,3 +57,6 @@
     'logo_only': True,
     'display_version': True,
 }
+html_css_files = [
+    'style.css',
+]
diff --git a/docs/deployment/local-deployment.rst b/docs/deployment/local-deployment.rst
@@ -0,0 +1,53 @@
+****************
+Local Deployment
+****************
+
+.. NOTE::
+
+   This part of documentation is currently **under development**.
+
+.. IMPORTANT::
+
+   This deployment is inteded only for testing purposes and should not serve for real production use. If you want to provide VODAN-in-a-Box to others, visit :ref:`production-deployment`.
+
+Requirements
+============
+
+- Docker Engine version 19.03
+
+Setup
+=====
+
+1. Download or ``git clone`` repository https://github.com/VODAN-Tech/vodan-deployment-basic locally
+2. Change working directory ``cd vodan-deployment-basic``
+3. Run ``docker-compose up -d``
+
+Persistence
+-----------
+
+Changing ports
+--------------
+
+If you need to change ports because you already use those for other services, you just need to adjust the mappings in ``docker-compose.yml`` file. For example, if you want to access FDP on other port than ``8081`` change the mapping ``8081:80`` to something else, e.g., ``8881:80``.
+
+Usage
+=====
+
+When VODAN-in-a-Box is running, you can access the following services:
+
+- http://localhost:8080 - DSW
+- http://localhost:8081 - FDP
+- http://localhost:8082 - BlazeGraph
+- http://localhost:27017 - MongoDB
+- http://localhost:3000 - DSW API
+
+For both DSW and FDP, you can use default admin account ``albert.einstein@example.com`` with password ``password``. BlazeGraph and MongoDB are by default without authentication.
+
+Notes
+=====
+
+For more information about docker-compose and its options, visit `Docker documentation <https://docs.docker.com/compose/>`_.
+
+Various advanced deployment options of FAIR Data Point are well-described in `FAIR Data Point Reference Implementation Documentation <https://fairdatapoint.readthedocs.io>`_.
+
+The main difference with respect to the :ref:`production-deployment` is the absence of proxy and certificates, with opened ports directly instead.
diff --git a/docs/deployment/production-deployment.rst b/docs/deployment/production-deployment.rst
@@ -0,0 +1,9 @@
+.. _production-deployment:
+
+*********************
+Production Deployment
+*********************
+
+.. NOTE::
+
+   This part of documentation is currently **under development**.
diff --git a/docs/index.rst b/docs/index.rst
@@ -2,8 +2,23 @@ VODAN in a Box Documentation
 ============================
 
 .. toctree::
-   :maxdepth: 2
    :caption: About
+   :maxdepth: 2
+
+   about/about
+   about/usage-scenarios
+   about/components
+
+.. toctree::
+   :caption: Deployment
+   :maxdepth: 2
+
+   deployment/local-deployment
+   deployment/production-deployment
+
+
+Indices and tables
+==================
 
    about/about
    about/usagescenarios