Contents

Change log:

Date:

Author:

Version:

Changes:

Completed

Ext.

Int.

Is in Core

Jira Ref.

0.1

Doc. created

Yes/No

x

 

N/A

 

This is a brief (and not necessarily complete) guide to install the REST in a Tomcat.

Install Tomcat 7

A Tomcat must be installed on your environment. Please ensure to get Tomcat 7 our core functionality do not support future versions.

Short installation guide

  1. Download the REST web app: http://cdrsrvbuild2:8080/jenkins/job/rator-selfcare-rest-API-TRUNK/ws/target/rator-selfcare-rest-api-0.0.1-SNAPSHOT.war
  2. Copy the war file to the Tomcat webapps directory and (re-)start the Tomcat application.
  3. Download the Swagger UI documentation web servce: TODO
  4. Copy the .dist folder to the <Tomcat root>/webapps/swagger-ui directory and (re-)start the Tomcat application. Nb This can be a different Tomcat installation than in step 2, or the same. TODO: Verify this
  5. In your browser, enter URL "http://<Swagger server and port>/swagger-ui/?url=http://<REST server and port>/api/swagger.json"

NB Your Tomcat installation's server.xml file will specify a base path for the REST project. If step 6 does not work, you must either modify the base path, or modify the URL accordingly. If you are deploying from Eclipse, you will want to specify the base path on the modules subpane of the server pane. The URL in step 6 assumes a <context/> entry a la the following ( - notice the empty string in the path parameter): 

<Context antiJARLocking="true" docBase="C:\Program Files\Tomcat\apache-tomcat-7.0.54\webapps\rator-selfcare-rest-api" path="" reloadable="true" source="org.eclipse.jst.jee.server:rator-selfcare-rest-api"/>

Resources

Source code is available both in our SVN repository, in Jenkins and in Nexus (where our Jenkins build deploys to).

The artifacts to deploy (the REST application and Swagger UI) can either be produced manually from source code (see below - Installation guide), downloaded from Nexus, or retrieved from Jenkins.

SVN

Please notice that the Swagger UI web service is not a Java project, but a collection of HTML, Javascript and CSS. 

Jenkins

Jobs are set up to do continuous integration. The artifacts produced from a build are placed in given the job's "Workspace" (Arbejdsområde) page, in the folder "target":

Nexus

Our Jenkins jobs are configured to deploy to Nexus. There, you can find both the source code and the artifacts produced from the build.

Build

You can build the artifacts yourself. Notice that the Swagger UI is not a Java project, for which reason its build procedure is different than the REST application.

rator-selfcare-rest-api

  1. Check out the source code (See the Resources paragraph above)
  2. Create the artifact: mvn clean package
  3. You should now have a rator-selfcare-rest-api-<version>.war file in the target folder.

Please notice that the REST project use Java 8 functionality. If your JAVA_HOME environment variable points to a jdk7, or below, you will get compile errors.

Since, in the time of writing, most other CDRator projects are compiled with jdk7, you might have your JAVA_HOME pointing to jdk7. In that case you need to change your JAVA_HOME. This can be done manually by Windows GUIs. In case you only want this change to be temporary, you can use the following convenience script (where you replace the path to jdk8 with your own installation):

@echo off
set prev_java_home=%JAVA_HOME%
set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_72
cmd /c mvn %*
set JAVA_HOME=%prev_java_home%

Place the script in a file called, fx, mvn8.bat and place the file in your apache-maven-<version>/bin folder (where an mvn.bat file should already be present). With this in place, the command in step 2 should be: mvn8 clean package

Developers working with the dependent project rator-core-api, should likewise be aware that this is a Java 8 application.

Swagger UI

TODO: Describe the npm and gulp command etc

  1. Check out the source code (See the Resources paragraph above.)
  2. npm install
  3. gulp
  4. You should see the distribution under the dist folder. Open ./dist/index.html to launch Swagger UI in a browser

Installation

  1. Retrieve the rator-selfcare-rest-api .war file (either from Jenkins/Nexus, see Resources, or by building the .war yourself, see Build.
  2. Copy the war file to the Tomcat webapps directory and (re-)start the Tomcat application.

 

If you are developing from Eclipse, and deploying to a local Tomcat installation, Eclipse automatically handles build and deployment. See fx the tomcat-section of this guide.

 

TODO: Swagger installation guide.

Verify installation

In your browser, enter URL "http://<Swagger server and port>/swagger-ui/?url=http://<REST server and port>/api/swagger.json"

(If you have installed the REST web app and the Swagger UI on the same Tomcat, <Swagger server and port> will be the same as <REST server and port>.)

This will display the list of available services.