Skip to content

QuickStart

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

Quick Start Guide

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

⚠️

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

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 checks

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 have a separate spring-boot/spring-batch project (not open-sourced) that processes CSV files exported from the application that was replaced by SciPaMaTo. The maven build compiles a jar file that will import the 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

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