Skip to content

QuickStart

Jump to bottom
Urs Joss edited this page May 27, 2019 · 15 revisions

Quick Start Guide

The quick-start assists you in getting the project up and running as quick as possible.

❗

It is a common best practice that a project can successfully compile (i.e. gradlew assemble) with no special preconditions to be met. This is not possible with scipamato. You need (at least) two running PostgreSQL databases to be able to compile the project.

The reason is my choice of using jOOQ to generate classes representing the database schema at build time (as opposed to committing the generated classes to the repository). This was a conscious trade-off, sacrificing unconditional compilation versus most up-to-date classes representing the database schema.

So in short: Do set up the database before trying to compile the project.
⚠️

This quickstart guide assumes you will strictly stick to the default settings, i.e. use the exact usernames/passwords as indicated. Also PostgreSQL is expected to run on the default port 5432.

It is easy to change all those settings (and you should for productive systems), but that will require additional configuration which is not within the scope of this quickstart guide. You can find more information on this further down on the page.

1. Summary

In order to work with the project, execute the following steps:

  1. Ensure the preconditions on your operating system are met

  2. Create the databases and users

  3. Clone the project from Github

  4. Build the project

  5. Run the applications

2. Preconditions

Ensure that the following preconditions are met:

  • Java 11 is installed

  • git is installed

  • PostgreSQL-Database is installed and running

  • You have permissions to create databases, users or can switch to a user that has them.

  • Your computer has internet access

Consult the internet on how to accomplish the installations for your operating system.

3. Prepare the databases

❗

Setting up two databases is a hard requirement for a successful compilation of the project.

We need two databases, one for SciPaMaTo-Core and one for SciPaMaTo-Public. I run integration tests against two additional databases [1], but these are optional. Leave those out if you don’t want to use them. [2]

With PostgreSQL running and with sufficient permissions (e.g as user postgres on Linux), run the following commands in your shell:

Create the regular databases for SciPaMaTo-Core and SciPaMaTo-Public
createdb -E utf8 scipamato
createdb -E utf8 scipamato_public

and — optionally — for the integration tests:

Consider creating the databases for integration tests
createdb -E utf8 scipamato_it
createdb -E utf8 scipamato_public_it

Connect to PostgreSQL (using pgsql, PGAdmin, DBeaver or whatever tool of your choice). Issue the following commands to create users and grant privileges as needed:

For database scipamato (SciPaMaTo-Core)
CREATE USER scipamadmin WITH CREATEROLE PASSWORD 'scipamadmin';
GRANT ALL PRIVILEGES ON DATABASE scipamato to scipamadmin WITH GRANT OPTION;
For database scipamato-public (SiPaMaTo-Public)
CREATE USER scipamadminpub WITH CREATEROLE PASSWORD 'scipamadminpub';
GRANT ALL PRIVILEGES ON DATABASE scipamato_public to scipamadminpub WITH GRANT OPTION;
Optionally: For database scipamato_it and scipamato_public_it (for integration tests)
GRANT ALL PRIVILEGES ON DATABASE scipamato_it to scipamadmin WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON DATABASE scipamato_public_it to scipamadminpub WITH GRANT OPTION;

4. Clone the project

git clone https://github.com/ursjoss/scipamato.git

5. Build the project

Building the project also applies the Flyway migrations. Change to the gradle root directory implementation/scipamato and build the project.

Build against the regular databases (scipamato and scipamato_public)
cd implementation/scipamato
./gradlew assemble

Gradle downloads all dependencies, builds the project, runs the flyway migrations in both regular databases that set up the tables and provide necessary reference data.

Optionally Build against the integration test databases (scipamato_it and scipamato_public_it)
./gradlew check

Gradle now applies the database migrations against all four databases, compiles the project, runs the unit tests, and runs the integration tests against the integration test databases.

6. Data-Transfer (optional and not part of the open-source project)

I created a separate spring-boot/spring-batch project (not open-sourced) that processes CSV files that were previously exported from the legacy application that was replaced by SciPaMaTo at SwissTPH. The maven build compiles a jar file that imports the exported and processed data into SciPaMaTo-Core.

Put this jar file into a directory, together with an application.properties file that has the correct jdbc-url, user name and password etc. configured for SciPaMaTo-Core

application.properties
#
# Application specific settings
#
##################################

#
# Logging specification
#
###########################

logging.file=log/migration.log
logging.level.root=INFO

#
# Database Configuration
#
#############################
db.schema=public
spring.datasource.type=com.zaxxer.hikari.HikariDataSource
spring.datasource.hikari.driver-class-name=org.postgresql.Driver
spring.datasource.hikari.jdbc-url=jdbc:postgresql://localhost:5432/scipamato
spring.datasource.hikari.username=scipamadmin
spring.datasource.hikari.password=scipamadmin
spring.datasource.hikari.connection-timeout=60000
spring.datasource.hikari.maximum-pool-size=7

To run the jar:

Import the data containing the data from the legacy application
java -jar ./ludok-migration-0.0.1-SNAPSHOT.jar
⚠️

If you want to import the data, be sure to do it before you start the application. Currently a bug creates the spring batch meta tables with the wrong permissions. Those ared both used for data import and for exporting data from core to public. If you start the application first, the data import will fail.

7. Run the applications

There are a few possibilities to run a spring boot project such as SciPaMaTo. This guide describes only one of them involving gradle.

7.1. Run SciPaMaTo-Core

From the root directory in the git repository:

cd implementation/scipamato/
./gradlew :core-web:bootRun

Open the web-browser and access https://localhost:8080/. You can login with username/password admin/admin.

7.2. Run SciPaMaTo-Public

From the root directory in the git repository:

cd implementation/scipamato/
./gradlew :public-web:bootRun

Open the web-browser and access https://localhost:8081/. No login is required for regular usage.

1. The separate databases have the advantage that you do not break the integration tests if you start modifying data through the Web-UI.
2. If you skip the creation of the integration test databases, you should not use the gradle tasks integrationTest or check as is instructed further down in the page.

SciPaMaTo - the Scientific Paper Management Tool

Clone this wiki locally