Table of contents

• Migration from version 13.2.x and lower
  • Debian/Ubuntu operating system
  • Docker
  • Red Hat Enterprise Linux 7 / CentOS 7
• How to install
  • Debian/Ubuntu operating system
  • Virtual Machine image
  • Docker
  • Red Hat Enterprise Linux 7 / CentOS 7 (RPM package)
    • Install PostgreSQL and set up a database
    • Install and configure Apache Tomcat
    • Install the MINERVA rpm
• Database
• Logs

Migration from version 13.2.x and lower

Minerva 14 and higher require Apache Tomcat 8. Previous versions could work on Apache Tomcat 7.

Debian/Ubuntu operating system

Migration will be done automatically on Debian/Ubuntu systems.

Docker

Pulling the newest version of docker-compose repository solves the tomcat8 dependency.

Red Hat Enterprise Linux 7 / CentOS 7

Before you install new version of MINERVA you would need to remove old rpm based tomcat:

sudo yum remove tomcat

And install new tomcat manually as described in the install section. Tomcat7 stored data in different place than manually installed tomcat8. Move the data to tomcat8 folder:

sudo mv /var/lib/tomcat/webapps/map_images /opt/tomcat/webapps/
sudo mv /var/lib/tomcat/webapps/minerva-big /opt/tomcat/webapps/

How to install

Debian/Ubuntu operating system

Installation instructions are for Debian (tested on stretch, buster) and Ubuntu (tested on 16.04, 18.04). Please install MINERVA using the following command:

curl -s https://minerva.pages.uni.lu/doc/scripts/install.sh -o minerva-install.sh; \
sudo bash minerva-install.sh; \
rm minerva-install.sh

login: admin
password: admin

Virtual Machine image

You can download an image of a virtual machine running Debian Linux and a working instance of MINERVA platform using the following link. Choose the version you would like to try and download minerva-*_release.ova file.

Suggested tool to open and use is Oracle VM VirtualBox.

Once the VM is running, run MINERVA platform by entering: http://localhost:8080/minerva/ in the web browser of the VM.

Use the following admin credentials to log in to the admin panel:

login: admin
password: admin

In case you’d like to configure the VM, root credentials are

login: root
password: 123qweasdzxc

Docker

We prepared a docker compose configuration. To make it running just clone the repository and start it:

git clone https://git-r3lab.uni.lu/minerva/docker.git
cd docker
docker-compose up

Once the container is installed, run MINERVA platform by entering: http://localhost:8080/minerva/ in the web browser.

Use the following admin credentials to log in to the admin panel:

login: admin
password: admin

Red Hat Enterprise Linux 7 / CentOS 7 (RPM package)

Install PostgreSQL and set up a database

yum install -y https://download.postgresql.org/pub/repos/yum/9.6/redhat/rhel-7-x86_64/pgdg-centos96-9.6-3.noarch.rpm
yum install -y postgresql96-server
/usr/pgsql-9.6/bin/postgresql96-setup initdb

Ensure that the database authentication on IPv4 on localhost is done with md5-based passwords by adding the following line to /var/lib/pgsql/9.6/data/pg_hba.conf

host    all             all             127.0.0.1/32            md5

Enable and start postgresql

systemctl enable postgresql-9.6
systemctl start postgresql-9.6

Create the MINERVA database user and the database

su - postgres -c "createuser -d -r -s map_viewer"
su - postgres -c "echo \"ALTER USER map_viewer WITH PASSWORD 'yourSecretPasswordHere';\"| psql"
su - postgres -c "createdb -O map_viewer map_viewer"

Install and configure Apache Tomcat

Minerva requires Apache Tomcat 8 or higher. CentOS provides only package for Tomcat 7. Therefore you need to install it manually.

Create a new tomcat group and tomcat user

sudo groupadd tomcat
sudo useradd -M -s /bin/nologin -g tomcat -d /opt/tomcat tomcat

Download Tomcat Binary

wget https://www-eu.apache.org/dist/tomcat/tomcat-8/v8.5.46/bin/apache-tomcat-8.5.46.tar.gz
sudo mkdir /opt/tomcat
sudo tar xvf apache-tomcat-8*tar.gz -C /opt/tomcat --strip-components=1

Update Permissions

cd /opt/tomcat
sudo chgrp -R tomcat /opt/tomcat
sudo chmod -R g+r conf
sudo chmod g+x conf
sudo chown -R tomcat webapps/ work/ temp/ logs/

Install Systemd Unit File. Create a file /etc/systemd/system/tomcat.service (you might want to change memory settings specified in CATALINA_OPTS):

# Systemd unit file for tomcat
[Unit]
Description=Apache Tomcat Web Application Container
After=syslog.target network.target

[Service]
Type=forking

Environment=JAVA_HOME=/usr/lib/jvm/jre
Environment=CATALINA_PID=/opt/tomcat/temp/tomcat.pid
Environment=CATALINA_HOME=/opt/tomcat
Environment=CATALINA_BASE=/opt/tomcat
Environment='CATALINA_OPTS=-Xms2048M -Xmx4096M -server -XX:+UseParallelGC'
Environment='JAVA_OPTS=-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom'

ExecStart=/opt/tomcat/bin/startup.sh
ExecStop=/bin/kill -15 $MAINPID

User=tomcat
Group=tomcat
UMask=0007
RestartSec=10
Restart=always

[Install]
WantedBy=multi-user.target

Reload Systemd to load the Tomcat unit file

sudo systemctl daemon-reload

Enable and start Tomcat

sudo systemctl enable tomcat
sudo systemctl start tomcat

Make sure to open the port (by default port 8080) to allow incoming connections, e.g. using firewalld this can be accomplished with

firewall-cmd --permanent --zone=public --add-port=8080/tcp

If SELinux is enabled on your machine make sure that tomcat is allowed to connect postgres (relevant stackoverflow post)

WARNING: Currently the initial administrator password of MINERVA is hardcoded, therefore make sure the MINERVA cannot be accessed from distrusted hosts until the password was changed.

Install the MINERVA rpm

Create a configuration file at /etc/minerva/db.properties so MINERVA knows how to connect to the database:

database.uri=jdbc:postgresql://localhost:5432/map_viewer
database.username=map_viewer
database.password=yourSecretPasswordHere

Download MINERVA rpm from https://webdav-r3lab.uni.lu/public/minerva/. Here is a link to version 14.0.0:

wget https://webdav-r3lab.uni.lu/public/minerva/14.0.0/minerva-14.0.0-1.el7.noarch.rpm

Install MINERVA with

yum install -y minerva-14.0.0-1.el7.noarch.rpm

Database

Currently MINERVA supports only postgresql database. We support versions 9.4>=, 10.0>=, 11.0>=. Database can be configured in a /etc/minerva/db.properties file. This file should look like:

database.uri=jdbc:postgresql://host:port/database_name
database.username=database_user
database.password=database_password

where:

• host - host where database is located (localhost for local instances)
• port - port on which postgres is listening (by default it should be 5432)
• database_name - name of the database
• database_user - user that has access to the database
• database_password - user password

Database should be empty when MINERVA is starting for the first time. It will be automatically initialized. It’s also possible run MINERVA on database with content from the former version (but at least 12.1). In such situation migration to the new schema will happen automatically on tomcat start.

Logs

Default MINERVA logs will be stored in ${sys:catalina.base}/logs/minerva.txt file, where ${sys:catalina.base} is tomcat home directory (typically it would be something like /var/lib/tomcat8/logs/minerva.txt). MINERVA uses log4j2 library as a logging mechanism. Logs can be customized by creating /etc/minerva/log4j2.properties file. Default configuration used by MINERVA is available here: log4j2.properties. More information how to configure log4j2 can be found on the library homepage.