Skip to content

OBP API Install Guide Bare Metal

Jump to bottom Edit New page
Simon Redfern edited this page Jun 15, 2017 · 42 revisions

Assumption

  • Instructions assume Debian Jessie server (but should work on other GNU/Linux distributions or UNIX as well)

Run OBP API in mapped mode using built in H2 database

  • Install git, maven, java 8, Jetty 9

  • Clone the OBP-API source code from the repositoty

    git clone https://github.com/OpenBankProject/OBP-API.git

  • Change the working directory to OBP-API and copy the configuration file

    cd OBP-API
cp src/main/resources/props/sample.props.template src/main/resources/props/default.props

  • Edit the configuration file src/main/resources/props/default.props and uncomment the following lines

    connector=mapped
db.driver=org.h2.Driver
db.url=jdbc:h2:./lift_proto.db;DB_CLOSE_ON_EXIT=FALSE
hostname=http://127.0.0.1:8080

  • Comment out the following lines in the configuration file

    #db.driver=org.postgresql.Driver
#db.url=jdbc:postgresql://localhost:5432/dbname?user=dbusername&password=thepassword

  • Build the WAR package for the OBP-API

    mvn package

Note that the packaging take a few minutes to finish.

  • When the packaging is completed, you will find the OBP-API-1.0.war file under the directory OBP-API/target/

  • (Optional) If you have to change settings on the configuration file after the application has been packaged, you can update the configuration in the packaged WAR file like so

    • First, make a directory structure as follows

      mkdir -p WEB-INF/classes/props/

    • Copy the edited props file to the props directory

      cp default.props WEB-INF/classes/props/

    • Update the default.props file inside the package using the jar command

      jar uf /path/to/package/OBP-API-1.0.war WEB-INF/classes/props/default.props

  • To run the application on Jetty, copy the OBP-API-1.0.war file to the /var/lib/jetty9/webapps directory and rename it as ROOT.war

  • You can now point your browser to http://localhost:8080

Run OBP API in mapped mode using built in H2 database (using Docker containers)

Assumption

  • This assumes that Docker Community Edition or Docker Enterprise Edition is installed on the server

Run OBP API in Docker Container

  • Using the steps from above, make the packaged OBP API software ready

  • Run the OBP API package inside the Jetty 9 Docker container (whose official image can be found on Docker Hub https://hub.docker.com/_/jetty/). You may want to change the container name or port forwarding as per your requirements.

    docker run -d \
--name obp-api \
-v /path/to/package/OBP-API-1.0.war:/var/lib/jetty/webapps/ROOT.war \ 
-p 8080:8080 \
jetty

  • You can now point your browser to http://localhost:8080

Run OBP API in mapped mode using local database

Assumptions

  • Instructions in this section assume that you have a PostgreSQL (or Oracle) database setup on the local server
  • Following instructions about database creation are for PostgreSQL only. Please use the equivalent commands if you have an Oracle DB

Run OBP API with local database

  • Create a database on PostgreSQL

    root@sandbox ~ # sudo -i -u postgres
postgres@sandbox:~$ psql
postgres=# CREATE DATABASE <dbname>;
postgres=# CREATE USER <username> WITH PASSWORD 'xxx';
postgres=# GRANT ALL PRIVILEGES ON DATABASE <dbname> to <username>;

  • Edit the API configuration file default.props so that the API uses the local database. Uncomment the following lines in the file

    db.driver=org.postgresql.Driver
db.url=jdbc:postgresql://localhost:5432/dbname?user=dbusername&password=thepassword

  • Make sure to replace dbname, dbusername, and thepassword as per your database's configuration

  • Comment out the following lines

    #db.driver=org.h2.Driver
#db.url=jdbc:h2:./lift_proto.db;DB_CLOSE_ON_EXIT=FALSE

  • Copy the edited props file to the props directory

    cp default.props WEB-INF/classes/props/

  • Update the default.props file inside the package using the jar command

    jar uf /path/to/package/OBP-API-1.0.war WEB-INF/classes/props/default.props

  • To run the application on Jetty, copy the OBP-API-1.0.war file to the /var/lib/jetty9/webapps directory and rename it as ROOT.war

  • You can now point your browser to http://localhost:8080

Run OBP API in mapped mode using local database (using Docker Containers)

Assumption

  • This assumes that Docker Community Edition or Docker Enterprise Edition is installed on the server

Run PostgresSQL and OBP API in Docker Containers

  • Edit the API configuration file default.props so that the API uses the PostgreSQL container. Update the following line in the file

    db.url=jdbc:postgresql://obp-postgres:5432/obp-api-db?user=obp-api-db-user&password=thepassword

  • Replace obp-postgres, obp-api-db, obp-api-db-user, and thepassword as required (but make sure that they are the same as the respective values of the environment variables for the PostgreSQL container below)

  • Update the default.props file inside the package using the jar command

    jar uf /path/to/package/OBP-API-1.0.war WEB-INF/classes/props/default.props

  • Run PostgreSQL using the postgres:9.5 official Docker image from Docker Hub. Use a local directory and map it to the /var/lib/postgresql/data of the container to persist the data.

    docker run -d \
--name obp-postgres \
-v /path/to/data/directory/dbdata:/var/lib/postgresql/data \
-e POSTGRES_USER=obp-api-db-user \
-e POSTGRES_PASSWORD=thepassword \
-e POSTGRES_DB=obp-api-db \
postgres:9.5

  • Run the OBP API package inside the Jetty 9 Docker container (whose official image can be found on Docker Hub https://hub.docker.com/_/jetty/). You may want to change the container name or port forwarding as per your requirements.

    docker run -d \
--name obp-api \
--link obp-postgres:obp-postgres \
-v /path/to/obp/OBP-API/target/OBP-API-1.0.war:/var/lib/jetty/webapps/ROOT.war \
-p 8080:8080 \
jetty9

  • You can now point your browser to http://localhost:8080

Run OBP API in mapped mode and OBP storage connected to PostgreSQL (Oracle) database

Intro

  • Akka is a toolkit and runtime for building highly concurrent, distributed, and resilient message-driven applications on the JVM. See http://akka.io

  • To use Akka, you want to have two different machines:

    • One considered remote which stores the data
    • One considered local which is the public facing side of the API, where your users will connect

  • Both run current versions of the Open Bank Project API, but configured and run differently.

Remote Models

  • Not all models have been ported yet to be retrieved via Akka. See modelsRemotedata in src/main/scala/bootstrap/liftweb/Boot.scala to get a current list.

Remote Side

  • Configure src/main/resources/default.props:
# Remote end gets data 'locally'
remotedata.enable=false
# Your remote's external IP address
remotedata.hostname=xx.xx.xx.xx # Replace with external IP address of the host  
# Arbitrary port of your choosing
remotedata.port=5448

# Optionally configure postgres, otherwise file-based H2 will be used 
remotedata.db.driver=org.postgresql.Driver
remotedata.db.url=jdbc:postgresql://localhost:5432/dbname?user=user&password=password

Run

Manual

#!/bin/sh

cd ${HOME}/OBP-API/ && /usr/bin/nohup /usr/bin/mvn compile exec:java -Dexec.mainClass="code.remotedata.RemotedataActors" -Dexec.args="standalone" > ${HOME}/akka_remote_api.log &

systemd

  • You can run with above using this unit: obp-remotedata.service 
[Unit]
Description=Open Bank Project Remotedata Standalone

[Service]
Type=simple
User=deploy
Group=deploy
SyslogIdentifier=obp-remotedata
Restart=on-failure
WorkingDirectory=/home/deploy/OBP-API
ExecStart=/usr/bin/mvn compile exec:java -Dexec.mainClass=code.remotedata.RemotedataActors -Dexec.args=standalone

[Install]
WantedBy=multi-user.target

Local OBP API Side

  • Configure src/main/resources/default.props:
# Local end gets data remotely
remotedata.enable=true
# Your remote's public IP address
remotedata.hostname=xx.xx.xx.xx # Replace with external IP address of the remote host
# Arbitrary port of your choosing, has to match remote above
remotedata.port=5448
# Timeout for connection attempts
remotedata.timeout = 1

Run

#!/bin/sh

cd ${HOME}/OBP-API/ && /usr/bin/nohup /usr/bin/mvn jetty:run -Djetty.port=8080 -DskipTests  > ${HOME}/akka_local_api.log &

  • Optionally, like the steps in the previous sections, copy the edited props file to the props directory

    cp default.props WEB-INF/classes/props/

  • Update the default.props file inside the package using the jar command

    jar uf /path/to/package/OBP-API-1.0.war WEB-INF/classes/props/default.props

  • To run the application on Jetty, copy the OBP-API-1.0.war file to the /var/lib/jetty9/webapps directory and rename it as ROOT.war

Run OBP API in Production mode connected to Kafka and Adapter

Assumptions

  • In this section we assume Debian Jessie server for hosting the OBP API, PostgreSQL host, Zookeeper cluster and Kafka cluster in place

Create Kafka Topics

  • Create two topics named Request and Response on the Kafka cluster (this assumes a 3-host cluster, please adjust as necessary)

    bin/kafka-topics.sh --create --zookeeper host1:2181,host2:2181,host3:2181 \ 
--replication-factor 3 --partitions 3 --topic Request

bin/kafka-topics.sh --create --zookeeper host1:2181,host2:2181,host3:2181 \
--replication-factor 3 --partitions 3 --topic Response

Update configurations

  • Rename the default.props file as production.default.props

  • Change the connector and include settings for Kafka and Zookeeper clusters

    connector=kafka_JVMcompatible

# Address to be used by consumer
kafka.zookeeper_host=zookeeper_cluster:2181 # Replace zookeeper_cluster as necessary
# Address to be used by producer
kafka.host=kafka_cluster:9092 # Replace kafka_cluster as necessary
kafka.request_topic=Request
kafka.response_topic=Response

Copy configuration file to OBP API package and run the API

  • Copy the edited props file to the props directory

    cp production.default.props WEB-INF/classes/props/

  • Update the default.props file inside the package using the jar command

    jar uf /path/to/package/OBP-API-1.0.war WEB-INF/classes/props/production.default.props

  • To run the application on Jetty, copy the OBP-API-1.0.war file to the /var/lib/jetty9/webapps directory and rename it as ROOT.war

  • You can now point your browser to http://localhost:8080

Add a custom footer
Add a custom sidebar
Clone this wiki locally