Skip to content

Operations

Jump to bottom
Urs Joss edited this page Oct 7, 2023 · 24 revisions

Installation

1. Initialize the database

  • Make sure you have a running installation of PostgreSQL (I use 15.4) - make sure it has UTF8 encoding (default on Linux, in case of windows, see here).

1.1. Initialize the Core database

  • Define your choice for the following core-specific properties (I’ll stick with the defaults further down - adjust if you use different ones - and you should at least specify a different password!):

    db_name

    name for the database in your Postgres instance (default scipamato)

    flyway.user

    the administrative user name for Flyway migration (default scipamadmin)

    flyway.password

    password for the above database user (default scipamadmin).

    db_host_core
    db_port_core

    Also keep the hostname and the port ready your PostgreSQL serving the core database listens on (default 5432 for PostgreSQL)

  • Create the database scipamato and the administrative user for the Flyway migrations.

    • As user postgres:

      createdb -E utf8 scipamato

      Start the PostgreSQL interactive terminal:

      psql
      CREATE USER scipamadmin WITH CREATEROLE PASSWORD 'scipamadmin';
GRANT ALL PRIVILEGES ON DATABASE scipamato to scipamadmin WITH GRANT OPTION;
ℹ️
 You’ll be able to change the password for the operational user scipamato later too.

1.2. Initialize the Public database

  • Define your choice for the following public-specific properties (I’ll stick with the defaults further down - adjust if you use different ones - and you should at least specify a different password!):

    db_name

    name for the database in your Postgres instance (default scipamato_public)

    flyway.user

    the administrative user name for Flyway migration (default scipamadminpub)

    flyway.password

    password for the above database user (default scipamadminpub).

    db_host_public
    db_port_public

    Also keep the hostname and the port ready your PostgreSQL serving the public database listens on (default 5432 for PostgreSQL)

  • Create the database scipamato_public and the administrative user for the Flyway migrations.

    • As user postgres:

      createdb -E utf8 scipamato_public

      Start the PostgreSQL interactive terminal:

      psql
      CREATE USER scipamadminpub WITH CREATEROLE PASSWORD 'scipamadminpub';
GRANT ALL PRIVILEGES ON DATABASE scipamato_public to scipamadminpub WITH GRANT OPTION;
ℹ️
 You’ll be able to change the password for the operational user scipamato later too.

2. Initialize the application

2.1. Initialize the core application

  • Create a target directory for the application (e.g. /opt/scipamato_core)

  • Copy the core-web-${version}.jar file into the target directory (I’m not showing the version here) and make it executable, e.g. on linux:
    chmod u+x core-web.jar

  • Provide the following file application.properties in the target directory (make sure you adjust the user names/passwords according to your choices above):

    server.port=8080

db.schema=public

sync.source.datasource.jdbc-url=jdbc:postgresql://${db_host_core}:${db_port_core}/scipamato
sync.source.datasource.username=scipamato
sync.source.datasource.password=scipamato

sync.target.datasource.jdbc-url=jdbc:postgresql://${db_host_public}:${db_port_public}/scipamato_public
sync.target.datasource.username=scipamadminpub
sync.target.datasource.password=scipamadminpub

sync.batch.datasource.username=scipamadmin
sync.batch.datasource.password=scipamadmin

    You can find other configuration options in the Configuration-Core Page

  • run the application in order to kick off the DB Flyway migration:

./core-web.jar

2.2. Initialize the public application

  • Create a target directory for the application (e.g. /opt/scipamato_public)

  • Copy the public-web-${version}.jar file into the target directory (I’m skipping the version here) and make it executable, e.g. on linux:
    chmod u+x public-web.jar

  • Provide the following file application.properties in the target directory (make sure you adjust user names/passwords according to your changes above):

    server.port=8081

# User name and password for accessing the actuator end-points
scipamato.management-user-name=admin
scipamato.management-user-password=admin

spring.datasource.url=jdbc:postgresql://${db_host_public}:${db_port_public}/scipamato_public
db.schema=public
spring.datasource.hikari.username=scipamatopub
spring.datasource.hikari.password=scipamatopub

# Database Migration with Flyway
spring.flyway.user=scipamadminpub
spring.flyway.password=scipamadminpub

    Other configuration options are described in the Configuration Public Page

  • run the application in order to kick off the DB Flyway migration:

./public-web.jar

3. Test drive your application

3.1. Test drive the core application

Start the core application again and access through the browser:

./core-web.jar

Access the application through the web browser, e.g. on http://localhost:8080/ (unless you changed the port in the configuration above)

3.2. Test drive the public application

Start the public application again and access through the browser:

./public-web.jar

Access the application through the web browser, e.g. on http://localhost:8081/ (unless you changed the port in the configuration above)

4. Implement the application into your operational environment and processes

  • Run as service

  • backup

  • monitoring

  • configuration management (e.g. ansible)

  • …​

It is a simple step to install a spring boot app like SciPaMaTo as a Linux service (systemd or the older sysvinit). I manage the entire configuration and also the deployment process with ansible.

For more general information on how to run a spring-boot application, refer to Spring Boot Documentation.

4.1. Monitoring

The spring boot project offers out of the box a number of features for operative purposes, it e.g. exports valuable information through it’s actuator endpoints.

A simple dashboard providing good insight is spring boot admin. SciPaMaTo already contains the dependency on spring-boot-admin-starter-client and only lacks the configuration to activate the registration in spring boot admin.

You need to provide the respective configuration parameters to SciPaMaTo (through start parameters, environment variables or a local application.properties - see Externalized Configuration)

4.1.1. Simple Configuration

ℹ️
 The following config was used for spring-boot-1.5. I guess it changed for spring-boot-2.0 but I have not had time yet to investigate this…​ 
management.security.enabled=false

spring.boot.admin.client.name=${scipamato.brand} # (1)
spring.boot.admin.url=${sba_url} # (1)
spring.boot.admin.username=${sba_user} # (1)
spring.boot.admin.password=${sba_password} # (1)

  1. ${scipamato.brand}, ${sba_url}, ${sba_user}, and ${sba_password} need to be replaced with the real values used in your environment.

4.2. Primer for a config with actuator security in place

It is advised to enable actuator security. However, this requires that SciPaMaTo is accessible through https instead of http, so spring boot admin can securely access the end-points through https.

I have tried this setup with a self signed certificate but did not quite manage to get it running. I suspect it’s because of the certificate, but did not follow up yet. Configuration so far:

spring.boot.admin.client.name=${scipamato.brand}
spring.boot.admin.url=${sba_url}
spring.boot.admin.username=${sba_user}
spring.boot.admin.password=${sba_password}
spring.boot.admin.client.metadata.user.name=${username_for_sba} # (1)
spring.boot.admin.client.metadata.user.password=${pw_for_sba} # (1)

  1. In addition to the placeholders already described in the previous section, you need to specify ${username_for_sba} and ${pw_for_sba}, credentials that are part of the admin role that may access the actuator endpoints. Those will be passed on to spring batch admin. The latter will use those credentials to retrieve the relevant information from SciPaMaTo.

Resources for enabling https:

5. Deployment

With a new release of SciPaMaTo, you will receive a new jar file for SciPaMaTo-Core and/or Public.

Stop the currently running services, replace the jars, and restart the service.

If necessary, database-migrations are performed by Flyway during the startup of the application.

SciPaMaTo - the Scientific Paper Management Tool

Clone this wiki locally