-
Notifications
You must be signed in to change notification settings - Fork 178
WebAPI Installation Guide
This page describes the database setup, maven build configuration and deployment of OHDSI/WebAPI to a Apache Tomcat environment. This application is Java-based, packaged as a WAR, and should be able to be deployed into any Java servlet container.
Comming Soon.
You can install the Oracle 11g XE core distribution from the following URL: http://www.oracle.com/technetwork/database/database-technologies/express-edition/downloads/index.html Follow your platform specific installation to install the binary and start the service. Remember the db admin user and password that is set during the installation process since this will be needed later to administer the server (creating new databases and adding new schemas).
###Oracle database administration For the database administration, we will be using the Oracle SQL Developer tool available from the Oracle Downloads URL above (found udner the ‘other downloads links at the bottom of the page). After launching and connecting to the Oracle DB (in this example called ‘local’), you are presented with the following UI: [oracle_sqldeveloper_welcome.png]
Creating the database Users and Roles If your environment already has application level administration and non-administrative access groups created, you can skip this section on creating the roles.
The oracle installation will contain a database instance, and roles and users should be created for administering the OHDSI database and for non-administrative access (ie: application access) to the database. In this example, however, we’ll be creating one user: ohdsi that will provide the schema that will host the WebAPI generated tables. In more advanced cases, you may have a special administrator account for applications that has certain rights on the databases to create tables, but for simplicity, we’ll be using the schema user to administer the tables and also serve as the application user context for the normal WebAPI operations.
For this example, we will not be creating any special database groups. We will use the schema user as the administrative account and runtime database user. This is not recommended for production environments: a separate admin and runtime user should be defined and granted the appropriate permissions for their roles.
In Oracle, schemas operate in a slightly different way than other database platforms. For purpose of this guide, we’ll be implementing a new schema as a user, but there are other tools (such as RCU) which can be used to create new schemas owned by existing users, but those tools are beyond the scope of this guide. In this simple setup, we will create a user 'ohdsi' which will be used as the administrative account for WebAPI and all tables will be created under this user's schema.
To create a user, expand the SYSTEM connection in oracle SQL developer, and navigate to Other Users. Right-click Other Users, and click ‘Create User’. The below screen will be displayed: [oracle_createuser.png]
Login: ohdsi Tab: Granted Roles Role Name: CONNECT, RESOURCE
Tab: System Privileges Privilege: UNLIMITED TABLESPACE After these values are set, the generated SQL to create this role is produced: -- USER SQL CREATE USER ohdsi IDENTIFIED BY {password} DEFAULT TABLESPACE "SYSTEM" TEMPORARY TABLESPACE "TEMP";
-- QUOTAS
-- ROLES GRANT "CONNECT" TO ohdsi ; GRANT "RESOURCE" TO ohdsi ; ALTER USER ohdsi DEFAULT ROLE "CONNECT","RESOURCE";
-- SYSTEM PRIVILEGES GRANT UNLIMITED TABLESPACE TO ohdsi ;
In this simple example, no special additional steps are required to prepare the schema. The user is granted all rights to create the tables under their own schema. However, permissions will be required to be granted to query the CDM tables (in this simple case, the CDM tables will be located under another user on the same Oracle instance). It is very important that the OHDSI tables are co-located with the CDM tables. In more advanced scenarios, this is not a hard restriction, but will require additional steps to configure the environment this way. The benefit of this complexity is the ability to execute OHSI analysis across multiple CDMs.
Download Maven binary zip from https://maven.apache.org/download.cgi Unzip to Program Files folder Add Maven bin folder to system path Make sure JAVA_HOME is set (Note: You will not be able to build multi-architecture R projects when JAVA_HOME is set)
##Cloning the WebAPI project Clone the WebApi project to a local folder, e.g.: git clone https://github.com/OHDSI/WebAPI.git
Modify the settings_oracle.xml file Specify user name, password, and location of the OHDSI schema (this was created as ‘ohdsi’ above). Note that the user should have read, write, and create privileges on the OHDSI schema because this user is the owner of the ‘ohdsi’ schema. Here is an example XML that is based on the above configuration:
<settings>
<profile>
<id>webapi-oracle</id>
<properties>
<datasource.driverClassName>oracle.jdbc.OracleDriver</datasource.driverClassName>
<datasource.url>jdbc:oracle:thin:@//127.0.0.1:1521/xe</datasource.url>
<datasource.username>ohdsi</datasource.username>
<datasource.password>{password}</datasource.password>
<datasource.dialect>oracle</datasource.dialect>
<datasource.ohdsi.schema>OHDSI</datasource.ohdsi.schema>
<flyway.datasource.driverClassName>${datasource.driverClassName}</flyway.datasource.driverClassName>
<flyway.datasource.url>jdbc:oracle:thin:@//127.0.0.1:1521/xe</flyway.datasource.url>
<flyway.datasource.username>ohdsi</flyway.datasource.username>
<flyway.datasource.password>{password}</flyway.datasource.password>
<flyway.locations>classpath:db/migration/oracle</flyway.locations>
</properties>
</profile>
</profiles>
</settings>Note: this file above is saved as /WebAPIConfig/settings_oracle.xml and will be referred to in the "Building the .war file" section.
You will need to download the Oracle JDBC driver, and install it into your local maven repository. Once you download the jar, you will need to execute the following maven command to install it into the local repository. The simplest way is to navigate via the CLI to the directory the JAR was downloaded to, and execute the following command:
mvn install:install-file -Dfile=ojdbc.jar -DgroupId=ojdbc -DartifactId=ojdbc -Dversion=6.0.0 -Dpackaging=jar
(The above is all a single line command.)