Documentation cleanup (#172)

* updated documentation
BBMRI-ERIC · Mar 27, 2023 · 59f6f26 · 59f6f26
1 parent 247d39b
commit 59f6f26
Show file tree

Hide file tree

Showing 5 changed files with 125 additions and 109 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -13,40 +13,6 @@ on:
       - master
 
 jobs:
-  unit-tests:
-    needs: build
-    runs-on: ubuntu-22.04
-
-    steps:
-      - name: Check out Git repository
-        uses: actions/checkout@v3
-
-      - name: Set up JDK 8
-        uses: actions/setup-java@v3
-        with:
-          java-version: '8'
-          distribution: 'temurin'
-          cache: 'maven'
-
-      - name: Generate settings.xml for Maven Builds
-        uses: whelk-io/maven-settings-xml-action@v20
-        with:
-          mirrors: >
-            [
-              {
-                "id": "central",
-                "mirrorOf": "central",
-                "url": "http://nexus.bbmri-eric.eu:8081/repository/maven-public/"
-              }
-            ]
-
-      - name: Run unit tests
-        run: mvn test
-
-      - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v3
-
-
   build:
     runs-on: ubuntu-22.04
 
@@ -61,17 +27,6 @@ jobs:
           distribution: 'temurin'
           cache: 'maven'
 
-      - name: Generate settings.xml for Maven Builds
-        uses: whelk-io/maven-settings-xml-action@v20
-        with:
-          mirrors: >
-            [
-              {
-                "id": "central",
-                "mirrorOf": "central",
-                "url": "http://nexus.bbmri-eric.eu:8081/repository/maven-public/"
-              }
-            ]
       - name: Build with maven
         run: mvn package -Dmaven.test.skip=true
 
@@ -82,7 +37,7 @@ jobs:
           path: target/negotiator.war
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v1
+        uses: docker/setup-qemu-action@v2
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v2
@@ -101,6 +56,28 @@ jobs:
           path: /tmp/negotiator.tar
 
 
+  unit-tests:
+    needs: build
+    runs-on: ubuntu-22.04
+
+    steps:
+      - name: Check out Git repository
+        uses: actions/checkout@v3
+
+      - name: Set up JDK 8
+        uses: actions/setup-java@v3
+        with:
+          java-version: '8'
+          distribution: 'temurin'
+          cache: 'maven'
+
+      - name: Run unit tests
+        run: mvn test
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v3
+
+
   system-tests:
     needs: unit-tests
     runs-on: ubuntu-22.04
@@ -127,9 +104,6 @@ jobs:
       - name: Run negotiator in docker
         run: docker run -d --name negotiator --network negotiator -p 8080:8080 -e POSTGRES_HOST="negotiator-db" -e AUTH="true"  negotiator:latest
 
-      - name: Install Node JS
-        uses: actions/setup-node@v1
-
       - name: Install newman
         run: |
           npm install -g newman
@@ -169,7 +143,7 @@ jobs:
         run: docker run -d --name negotiator --network negotiator -p 8080:8080 -e POSTGRES_HOST="negotiator-db" -e AUTH="true"  negotiator:latest
 
       - name: Set up Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: '3.10'
 
@@ -211,18 +185,6 @@ jobs:
           distribution: 'temurin'
           cache: 'maven'
 
-      - name: Generate settings.xml for Maven Builds
-        uses: whelk-io/maven-settings-xml-action@v20
-        with:
-          mirrors: >
-            [
-              {
-                "id": "central",
-                "mirrorOf": "central",
-                "url": "http://nexus.bbmri-eric.eu:8081/repository/maven-public/"
-              }
-            ]
-
       - name: Initialize CodeQL
         uses: github/codeql-action/init@v2
         with:
@@ -288,7 +250,7 @@ jobs:
         run: docker load --input /tmp/negotiator.tar
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v1
+        uses: docker/setup-qemu-action@v2
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v2

diff --git a/.mvn/settings.xml b/.mvn/settings.xml
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<settings xmlns="http://maven.apache.org/SETTINGS/1.1.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd">
+
+    <mirrors>
+        <mirror>
+            <id>central</id>
+            <name>central</name>
+            <url>http://nexus.bbmri-eric.eu:8081/repository/maven-public/</url>
+            <mirrorOf>central</mirrorOf>
+        </mirror>
+    </mirrors>
+
+</settings>
diff --git a/README.md b/README.md
@@ -4,57 +4,29 @@
 ![Latest Release](https://img.shields.io/github/v/release/bbmri-eric/negotiator-v2)
 ![Docker Image Size (latest by date)](https://img.shields.io/docker/image-size/bbmrieric/negotiator)
 
+## Purpose
 
-## Getting Started
-The simplest way to spin up a negotiator instance is using docker. The commands bellow will start an instance with test
-data and the authentication disabled:
-
-`docker network create negotiator`
-
-`docker run --name negotiator-db --network negotiator -p 5432:5432 -e POSTGRES_PASSWORD=negotiator -e POSTGRES_USER=negotiator -e POSTGRES_DB=negotiator -d postgres:14`
-
-`docker run -d --name negotiator --network negotiator -p 8080:8080 -e POSTGRES_HOST="negotiator-db" -e AUTH="true"  bbmrieric/negotiator`
-## Development mode
-
-By settings the runtime property `de.samply.development.authenticationDisabled` to `true` in the bbmri.negotiator.xml,
- the application is started in development mode, that means:
-
-- You don't need to be authenticated from PERUN (our identity provider) to use the application. You can just select one
-  of the two roles at the login screen.
-
-- You can run the application without connecting it with a directory. This would mean that you can not make/edit queries. 
-  However, you can still work with dummy queries given in the dummy data.   
-
-- You can create dummy data by setting `de.samply.development.deployDummyData` to `true`(Also in the bbmri.negotiator.xml).
-
-Now if the application is started; after creating the database, the dummy data would be added to the database. 
-
-The directory synchronization task fails in this case(because there is no connection to the directory) but that should 
-not effect working of the negotiator. The directory synchronization can also be switched off by commenting out the 
-following line from de.samply.bbmri.negotiator.listener.ServletListner.java
-
-`timer.schedule(new DirectorySynchronizeTask(), 10000, 1000 * 60 * 60);` 
+The purpose of the negotiator is to serve academic researchers seeking bio-specimen and data for their research
+by providing a place for structured negotiations with partner [biobanks](https://www.sciencedirect.com/topics/nursing-and-health-professions/biobank). By streamlining the entire negotiation process the BBMRI-ERIC negotiator
+facilitates access and simplifies the communication between researchers and BBMRI-ERIC biobanks about availability of samples and data for research.
 
+## Current state
 
-## Installation
-
-When installing it on a server, copy the file WEB-INF/lib/postgresql-9.3-1102-jdbc41.jar to the tomcat lib directory 
-(/usr/share/tomcat7/lib/ on Ubuntu)
-
-If you want to store the database configuration details on the server, copy the file META-INF/context.xml to 
-/etc/tocmcat7/Catalina/localhost/ROOT.xml (if the application is deployed as 
-ROOT.war, otherwise change the xml name accordingly) and change the values in the ROOT.xml file to the real values for 
-the server.
-Otherwise the values of the META-INF/context.xml file are taken.
-
-
-## Code generation with jooq
+Using the BBMRI-ERIC [Directory](https://directory.bbmri-eric.eu/#/) or the [GBA SampleLocator](https://samplelocator.bbmri.de/) researchers can browse and locate
+a biobank's available resources, and then request access via the [Negotiator](https://negotiator.bbmri-eric.eu/).
 
+## Getting Started
+The simplest way to spin up a negotiator instance is using docker. The commands bellow will start an instance with test
+data and the authentication disabled:
 
+```sh
+docker network create negotiator
+docker run --name negotiator-db --network negotiator -p 5432:5432 -e POSTGRES_PASSWORD=negotiator -e POSTGRES_USER=negotiator -e POSTGRES_DB=negotiator -d postgres:14
+docker run -d --name negotiator --network negotiator -p 8080:8080 -e POSTGRES_HOST="negotiator-db" -e AUTH="true"  bbmrieric/negotiator
+```
 
-You can then generate the classes by running the following command:
+## Documentation
+* [Development](development.md)
+* [Deployment](deployment.md)
 
 
-```
-mvn org.jooq:jooq-codegen-maven:generate
-```
diff --git a/deployment.md b/deployment.md
@@ -0,0 +1,10 @@
+## Installation
+
+When installing it on a server, copy the file WEB-INF/lib/postgresql-9.3-1102-jdbc41.jar to the tomcat lib directory
+(/usr/share/tomcat7/lib/ on Ubuntu)
+
+If you want to store the database configuration details on the server, copy the file META-INF/context.xml to
+/etc/tocmcat7/Catalina/localhost/ROOT.xml (if the application is deployed as
+ROOT.war, otherwise change the xml name accordingly) and change the values in the ROOT.xml file to the real values for
+the server.
+Otherwise the values of the META-INF/context.xml file are taken.
diff --git a/development.md b/development.md
@@ -0,0 +1,57 @@
+# Development
+## Database
+
+To run the application in development mode you first need to spin up a database. We currently support postgres:14. The simplest way is to create a postgres docker container with default credentials for the application:
+```sh
+docker run --name negotiator-db --network negotiator -p 5432:5432 -e POSTGRES_PASSWORD=negotiator -e POSTGRES_USER=negotiator -e POSTGRES_DB=negotiator -d postgres:14
+```
+
+
+## Application
+For the next step please rename the [bbmri.negotiator.example.xml](src/main/resources/bbmri.negotiator.example.xml) in _**src/main/resources**_ to: src/main/resources/bbmri.negotiator.xml
+
+
+By settings the runtime property `de.samply.development.authenticationDisabled` to `true` in the [bbmri.negotiator.xml](src/main/resources/bbmri.negotiator.xml),
+the application is started in development mode, that means:
+
+- You don't need to be authenticated from [PERUN](https://perun-aai.org/) (our identity provider) to use the application. You can just select one
+  of the roles at the login screen.
+
+- You can run the application without connecting it to a directory. This would mean that you can not make/edit queries.
+  However, you can still work with dummy queries given in the dummy data.
+
+- You can create dummy data by setting `de.samply.development.deployDummyData` to `true`(Also in the bbmri.negotiator.xml).
+
+Now if the application is started; after creating the database, the dummy data would be added to the database.
+
+The directory synchronization task fails in this case(because there is no connection to the directory) but that should
+not affect working of the negotiator. The directory synchronization can also be switched off by commenting out the
+following line from de.samply.bbmri.negotiator.listener.ServletListner.java
+
+`timer.schedule(new DirectorySynchronizeTask(), 10000, 1000 * 60 * 60);`
+
+## [Maven](https://maven.apache.org/)
+We use maven as our project management tool. So if you don't have it already installed please do so and verify that everything was installed correctly by running:
+
+`mvn version`
+
+NOTE: The **_.mvn/settings.xml_** file is for adding a mirror to download our legacy libraries from an internal nexus.
+
+Now to create the war package simply run the following command in the project directory:
+
+`mvn clean package`
+
+To deploy the WAR file to Tomcat please follow this **[guide](https://www.baeldung.com/tomcat-deploy-war)** or run it using tomcat configuration in InteliJ Ultimate as decribed [here](https://www.jetbrains.com/idea/guide/tutorials/working-with-apache-tomcat/using-existing-application/).
+
+## Testing
+
+For acceptance tests we use the [Selenium IDE](https://www.selenium.dev/selenium-ide/) to generate high level and human-readable tests.
+If you would like to add some please export them to python (Click export test suite, select format) and copy them to _**.github/tests/test_use-cases.py**_
+
+## Code generation with jooq
+
+You can then generate the classes for new a database schema by running the following command:
+
+```
+mvn org.jooq:jooq-codegen-maven:generate
+```