1. Just Biotherapeutics Avatar Just Biotherapeutics
  2. JStruct
  3. JStruct

Wiki

Clone wiki

JStruct / System Install Guide

View History

<< return to Home page

1. Requirements

1.1 Linux Server

A Linux server (or VM) with a minimum of 4 cores, 8 GB of RAM, and 150-200 GB of disk space should be used.

1.2 Java

JStruct uses Java 1.8:

1.3 Apache Maven

Maven is used for the project's build:

  • https://maven.apache.org/

1.4 Apache Tomcat Server

JStruct is deployed within the Apache Tomcat application server. It has been deployed to version 8.0.32

  • http://tomcat.apache.org/

1.5 PostgreSQL database

PostgresSQL 9.3.13 and 9.5.1 have been tested (on Ubuntu)

  • https://www.postgresql.org/

2. Install

2.1 Service Account

An existing service account (e.g. svc-jstruct) should be identified for managing the JStruct system, or a new service account should be created. The Tomcat application server and PostgreSQL database should be run by this account, and this account should own their directories and files.

2.2 Java

Download and install the latest version of JDK 1.8 from Oracle: http://www.oracle.com/technetwork/java/javase/downloads/index.html

Apache Maven is used for building the application distribution. If it is not already installed on the system, download it from: https://maven.apache.org/download.cgi.

2.3 Apache Tomcat

Download and install the latest version of Apache Tomcat 8.x (http://tomcat.apache.org/download-80.cgi). If you encounter problems with a specific version of the server fall back to a tested version.

Edit the server.xml file (change the port numbers to unique ports within your environment)

<Server port="5503" shutdown="SHUTDOWN"> ... </Server>


<Connector port="5501" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="5502" />

<Connector port="5504" protocol="AJP/1.3" redirectPort="8443" />
If https support is desired, see the SSL section and follow the instructions at http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html. Once you have a certificate in a keystore, you can configure the Tomcat server.xml thusly: 
<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
           port="8443" maxThreads="200"
           scheme="https" secure="true" SSLEnabled="true"
           keystoreFile="/apps/tomcat/certs/keystore"
           keystorePass="jstruct"
           clientAuth="false" sslProtocol="TLS"
           maxParameterCount="-1"  maxPostSize="-1"/>

2.4 SSL Certificates

Use of JStruct does not require SSL encryption but its use is recommended to provide additional security. If you have an internal certificate authority for issuing certificates, you will need to generate a certificate for the Tomcat server.

A single self-signed certificate for the Apache HTTP server can be generated thusly:

# Create a certificate in a keystore for Tomcat:
> keytool -genkey -alias tomcat -keyalg EC -keystore ~/.keystore
# In the conf directory of the HTTP server, create a temporary PKCS12 keystore and then extract the certificate and private key files to be reference in the extra/http-ssl.conf:
> keytool -importkeystore -srckeystore ~/.keystore -destkeystore keystore.p12 -deststoretype PKCS12 -srcalias tomcat -deststorepass password -destkeypass password
> openssl pkcs12 -in keystore.p12 -nokeys -out sslcert.pem
> openssl pkcs12 -in keystore.p12 -nodes -nocerts -out sslkey.pem

If you have an existing certificate, you can import it into a keystore for Tomcat like this: 

# Export your key, certificate and ca-certificate into a PKCS12 bundle via:
> openssl pkcs12 -export -in my.crt -inkey my.key -CAfile my-ca-file.crt -caname root -name tomcat -out jstruct.p12
# Import the PKCS12 file into a new java keystore via:
> keytool -importkeystore -destkeystore keystore -srckeystore jstruct.p12 -srcstoretype PKCS12 -alias tomcat

2.5 PostgreSQL Database

Dowload and install the latest version of PostgreSQL database server (https://www.postgresql.org/). JStruct has been tested on 9.3.14 and 9.5.1

Edit the postgresql.conf file:

line comment
port = 5500 update port number (enter unique port number for your environment)
shared_buffers = 2GB increase shared_buffers to 2GB
work_mem = 256MB set work_mem to 256MB

Use psql to create and set the password for the postgres account: 

> sudo -u postgres psql

postgres=# \password
Enter new password:
Enter it again:
postgres=# \q

Use psql to create the jstruct database: 

> sudo -u postgres psql --command="CREATE DATABASE jstruct"

Use psql to create the jstruct_rw account: 

> sudo -u postgres psql --command="CREATE USER jstruct_rw WITH PASSWORD 'paZZwerd';"

Place the login credentials for the jstruct_rw account into the .credMgr file in the service account's home directory. This is where the webapp will look for database access credentials. The .credMgr file is a text file readable only be the owner (permissions -rw------) that has a line format of <key name> <login name> <password>. The key names that you specify need to match the values that you use in the webapp's context.xml file. (see section 2.8)

2.6 Schema

The JStruct distribution contains a releases directory which contains sql scripts for each version. To setup the database for the most recent release, run the scripts in the folder with the largest version number, in order*: 

> psql postgres -h localhost -d jstruct -f ./init_xxx_PROD.sql
> psql postgres -h localhost -d jstruct -f ./schema_xxx.sql

Prior to running the init sql file, update the following information:

  • change the jstruct_rw password to the same one set in the previous step
  • change the email addresses for the default users (System and Guest)

* note: when setting up the develoment environment, replace the init_xxx_PROD.sql file with init_xxx_DEV.sql

2.7 PostgreSQL backups

In the home directory of the service account that will take database backups, configure a .pgpass file according to http://www.postgresql.org/docs/9.4/static/libpq-pgpass.html.

Example backup scripts can be found at: https://wiki.postgresql.org/wiki/Automated_Backup_on_Linux.

Add a cron entry to trigger the backups. For example: 

# Backup the postgresql database each night at 9pm
0 21 * * * /home/svc-jstruct/postgres_backups/bin/pg_backup_rotated.sh -c pg_backup.config

2.8 Create a .credMgr file

In order to keep passwords out of the source code and centrally managed, a special file called .credMgr needs to be present in the home directory of the user (or service account) running the application. This file should only be read/writable by the user (permissions rw-------).

Credentials are stored as three space-separated fields: <key> <username> <password> The JStruct PostgreSQL password should be stored like: 

#key          username      password
#----------   -----------   -----------
jstruct_rw    jstruct_rw    paZZwerd

* Lines beginning with a pound sign (#) are treated as comments and thus ignored.

3. Download Source

3.1 Source code

Source code is stored in BitBucket, and can be downloaded from: https://bitbucket.org/JustBiotherapeutics/jstruct/src

3.2 Dependencies

After source is downloaded, download all dependencies in...

4. Configuration

The source code currently contains files for local (development) and production environments, which will need to be updated for your specific instance. The steps below reference the production environment; update this data for local, development, and test as necessary.

4.1 Maven setup

JStruct uses Maven build profiles in the pom.xml to target different resources/settings for each environments build.

Ensure the following lines are in the tomcat-users element of the tomcat_users.xml file: 

  <role rolename='manager' />
  <role rolename='manager-gui' />
  <role rolename='manager-script' />
  <user username='tomcat' password='paZZwerd' roles='manager,manager-gui,manager-script' />

Add authentication info for this same username to the <servers> element in the Maven settings.xml file. 

  <servers>
    ...
    <server>
      <id>jstruct-prod</id>
      <username>tomcat</username>
      <password>paZZwerd</password>
    </server>
    <!-- uncomment to setup local development environment
    <server>
      <id>jstruct-local</id>
      <username>tomcat</username>
      <password>paZZwerd</password>
    </server> -->
  </servers>

4.2 Persistence settings

JStruct uses Hibernate for its ORM, and HikariCP for connection pooling. Most configuration for these frameworks is found in the persistence.xml file.

Production environment, src\main\filters\prod\META-INF\persistence.xml - example: 

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.1" xmlns="http://xmlns.jcp.org/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd">

    <persistence-unit name="JSTRUCT_PERSISTENCE_UNIT" transaction-type="RESOURCE_LOCAL">

        <provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>

        <exclude-unlisted-classes>false</exclude-unlisted-classes>

        <properties>

            <property name="hibernate.connection.provider_class" value="com.zaxxer.hikari.hibernate.HikariConnectionProvider" />

            <property name="hibernate.hikari.minimumIdle" value="10" />
            <property name="hibernate.hikari.maximumPoolSize" value="20" />
            <property name="hibernate.hikari.connectionTimeout" value="10000" />
            <property name="hibernate.hikari.maxLifetime" value="1800000" />

            <property name="hibernate.hikari.dataSourceClassName" value="org.postgresql.ds.PGSimpleDataSource" /> 
            <property name="hibernate.hikari.dataSource.url" value="jdbc:postgresql://servername.justbiotherapeutics.com:5500/jstruct" />

            <property name="hibernate.show_sql" value="false"/>
            <property name="hibernate.format_sql" value="false"/>

        </properties>

    </persistence-unit>
</persistence>

* at a minimum, the hibernate.hikari.dataSource.url value must be updated

4.3 ApplicationResources.properties file

Production environment, src\main\filters\prod\ApplicationResources.properties - example: 

# URLs
PermalinkBaseUrl=http://jstruct.justbiotherapeutics.com:5501/jstruct/

# Authentication
LDAP_ServerURL=ldap://justbiotherapeutics.com
LDAP_PrincipalFieldName=userPrincipalName
LDAP_UserContext=OU=Users,OU=Just,DC=justbiotherapeutics,DC=com
DomainRestriction=justbiotherapeutics.com
DefaultDomain=justbiotherapeutics.com

# Persistence
CredMgrFile=/home/svc-jdesign/.credMgr
CredMgrKey=jstruct_rw

# Version Info 
AppVersion=1.x.x
AppDate=1986-02-19
AppDatabase=servername.justbiotherapeutics.com:5500/jstruct
AppInstance=production
AppFullInstance=JStruct production environment

4.4 Other properties files

Additional properties files are found in the same folder (src\main\filters\prod\*.properties) - keep their settings or update as necessary:

  • logging.properties
  • quartz.properties
  • quartz_solo.properties

5. Build and Deploy

5.1 Start Tomcat

Run the startup.sh command in Tomcat's bin folder to start the web server.

5.2 Build and Deploy

From the command line, change directory into the project root (where the pom.xml script is), and run the build/deploy command:

for Production: 

> mvn -Pprod clean package tomcat:deploy
* if JStruct is already up and running, run the undeploy command first: mvn -Pprod tomcat:undeploy

==TODO:==

6. First Use

6.x Startup

6.x RCSB Import

6.x Manual Upload

Appendix A. Development Environment examples

Example - src\main\filters\local\ApplicationResources.properties

# URLs
PermalinkBaseUrl=http://localname.justbiotherapeutics.com:8080/jstruct/

# Authentication
LDAP_ServerURL=ldap://justbiotherapeutics.com
LDAP_PrincipalFieldName=userPrincipalName
LDAP_UserContext=OU=Users,OU=Just,DC=justbiotherapeutics,DC=com
DomainRestriction=justbiotherapeutics.com
DefaultDomain=justbiotherapeutics.com

# Persistence
CredMgrFile=/home/username/.credMgr
CredMgrKey=jstruct_rw

# Version Info 
AppVersion=1.x.x
AppDate=21986-02-19
AppDatabase=localhost:5432/jstruct
AppInstance=local
AppFullInstance=JStruct local development environment

Example - src\main\filters\local\META-INF\persistence.xml

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.1" xmlns="http://xmlns.jcp.org/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd">

    <persistence-unit name="JSTRUCT_PERSISTENCE_UNIT" transaction-type="RESOURCE_LOCAL">

        <provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>

        <exclude-unlisted-classes>false</exclude-unlisted-classes>

        <properties>

            <property name="hibernate.connection.provider_class" value="com.zaxxer.hikari.hibernate.HikariConnectionProvider" />

            <property name="hibernate.hikari.minimumIdle" value="10" />
            <property name="hibernate.hikari.maximumPoolSize" value="20" />
            <property name="hibernate.hikari.connectionTimeout" value="10000" />
            <property name="hibernate.hikari.maxLifetime" value="1800000" />

            <property name="hibernate.hikari.dataSourceClassName" value="org.postgresql.ds.PGSimpleDataSource" /> 
            <property name="hibernate.hikari.dataSource.url" value="jdbc:postgresql://localhost:5432/jstruct" />

            <property name="hibernate.show_sql" value="false"/>
            <property name="hibernate.format_sql" value="false"/>


        </properties>

    </persistence-unit>
</persistence>

Appendix B. Development build and deploy commands

> mvn -Plocal tomcat:undeploy
> mvn -Plocal clean package tomcat:deploy

Updated