README.md 3.58 KB
Newer Older
Piotr Gawron's avatar
Piotr Gawron committed
1
[![build status](https://git-r3lab.uni.lu/minerva/core/badges/master/pipeline.svg)](https://git-r3lab.uni.lu/minerva/core/badges/master/pipeline.svg)
Piotr Gawron's avatar
Piotr Gawron committed
2
[![coverage report](https://git-r3lab.uni.lu/minerva/core/badges/master/coverage.svg)](https://git-r3lab.uni.lu/minerva/core/commits/master)
Piotr Gawron's avatar
Piotr Gawron committed
3

Piotr Gawron's avatar
Piotr Gawron committed
4 5
# For users
Documentation for minerva can be found here: https://minerva.pages.uni.lu/doc/
6

Piotr Gawron's avatar
Piotr Gawron committed
7
# For developers
8

Piotr Gawron's avatar
Piotr Gawron committed
9
## Installation
10

Piotr Gawron's avatar
Piotr Gawron committed
11 12
After cloning repo you need to install following tools:
* postgresql (>=9.1)
Piotr Gawron's avatar
Piotr Gawron committed
13
* tomcat (tested on tomcat8, tomcat9)
Piotr Gawron's avatar
Piotr Gawron committed
14
* Java8 - works on OpenJDK 8, Oracle Java 8, OpenJDK 11
Piotr Gawron's avatar
Piotr Gawron committed
15 16 17
* maven
* ant
* node.js + npm
18

Piotr Gawron's avatar
Piotr Gawron committed
19
You need to create user and database:
20
```
Piotr Gawron's avatar
Piotr Gawron committed
21 22 23
username: map_viewer
password: 123qweasdzxc
dbname: map_viewer
24 25
```

Piotr Gawron's avatar
Piotr Gawron committed
26
If you want to use different credentials or your database in not hosted locally you can configure it by creating file `/etc/minerva/db.properties`. Template of the file can be found here: https://git-r3lab.uni.lu/minerva/core/blob/master/persist/src/main/resources/db.properties
27

Piotr Gawron's avatar
Piotr Gawron committed
28
Database schema is managed automatically by [flyway](https://flywaydb.org/), so there is no need to populate the database with anything.
29

Piotr Gawron's avatar
Piotr Gawron committed
30 31
Now your dev environment is configured and ready to use. To test it you can run unit tests:
* back-end - go to one of the Java modules (ie 'persist') and call mvn test:
32
```
Piotr Gawron's avatar
Piotr Gawron committed
33 34
cd ~/workspace/minerva/commons/
mvn test
35
```
Piotr Gawron's avatar
Piotr Gawron committed
36
* front-end - go to module with front-end, install all npm dependencies and run tests:
37
```
Piotr Gawron's avatar
Piotr Gawron committed
38 39 40
cd ~/workspace/minerva/frontend-js/
npm install
npm test
41 42
```

Piotr Gawron's avatar
Piotr Gawron committed
43
## Build
44

Piotr Gawron's avatar
Piotr Gawron committed
45
To build `*.war` file that can be deployed on tomcat you need to call ant maven-build task:
46
```
Piotr Gawron's avatar
Piotr Gawron committed
47 48
cd ~/workspace/minerva/
ant maven-build
49
```
Piotr Gawron's avatar
Piotr Gawron committed
50
This will create `~/workspace/minerva/web/target/web-1.0.war` file which can be deployed on tomcat:
51
```
Piotr Gawron's avatar
Piotr Gawron committed
52
cp ~/workspace/minerva/web/target/web-1.0.war $CATALINA_HOME/webapps/minerva.war
53 54
```

Piotr Gawron's avatar
Piotr Gawron committed
55 56
After starting tomcat you can access minerva using http://localhost:8080/minerva/.
Default credentials are:
57
```
Piotr Gawron's avatar
Piotr Gawron committed
58 59
login: admin
password: admin
60 61
```

Piotr Gawron's avatar
Piotr Gawron committed
62 63
## Deployment and release
Before making new release update [changelog file](https://git-r3lab.uni.lu/minerva/core/blob/master/CHANGELOG).
Piotr Gawron's avatar
Piotr Gawron committed
64

Piotr Gawron's avatar
Piotr Gawron committed
65 66
### Debian packages
When all the changes are ready tag commit and push it to the repository. Gitlab ci will execute unit tests and prepare distribution files that can be released. For now we release minerva using debian repository. Therefore gitlab ci creates a deb package (for instance: https://git-r3lab.uni.lu/minerva/core/-/jobs/29918). This package should be uploaded to our repository:
67
```
Piotr Gawron's avatar
Piotr Gawron committed
68 69
echo 'PUT minerva_12.0.3_amd64.deb'| sftp -P 8022 repo-r3lab.lcsb.uni.lu
ssh repo 'sudo reprepro -b /var/www/html/debian includedeb test minerva_12.0.3_amd64.deb'
70 71
```

Piotr Gawron's avatar
Piotr Gawron committed
72 73 74 75
Remember to use proper repository:
* stable - for production ready debian packages
* test - for packages that are ready to test and probably will be moved to stable soon
* experimental - for packages that might crash, can be unstable are created during development process (anything that has `alpha`, `beta` in the version number should be put here)
76

Piotr Gawron's avatar
Piotr Gawron committed
77
Moreover we store all debian packages on webdav:
78
```
Piotr Gawron's avatar
Piotr Gawron committed
79
echo 'put minerva_12.0.3_amd64.deb' | cadaver https://webdav-r3lab.uni.lu/public/minerva/
80 81
```

Piotr Gawron's avatar
Piotr Gawron committed
82
### Docker image
Piotr Gawron's avatar
Piotr Gawron committed
83
Update minerva [docker repository](https://git-r3lab.uni.lu/minerva/docker).
David Hoksza's avatar
David Hoksza committed
84

Piotr Gawron's avatar
Piotr Gawron committed
85 86
### VirtualBox images
We provide also VirtualBox images with minerva installed  on it. Just create a new debian virtual box image and upload it to webdav:
David Hoksza's avatar
David Hoksza committed
87
```
Piotr Gawron's avatar
Piotr Gawron committed
88
echo 'put minerva-12.0.1_release.ova' | cadaver https://webdav-r3lab.uni.lu/public/minerva/
David Hoksza's avatar
David Hoksza committed
89 90
```

Piotr Gawron's avatar
Piotr Gawron committed
91
Image should have root account with `123qweasdzxc` password. It should also expose port 8080 on the host.