README.md 3.58 KB
Newer Older
Piotr Gawron's avatar
Piotr Gawron committed
1
[![build status](https://git-r3lab.uni.lu/piotr.gawron/minerva/badges/master/build.svg)](https://git-r3lab.uni.lu/piotr.gawron/minerva/commits/master)
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 tomcat7, tomcat8)
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.