|
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.
A Tomcat must be installed on your environment. Please ensure to get Tomcat 7 our core functionality do not support future versions.
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. |
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.
Please notice that the Swagger UI web service is not a Java project, but a collection of HTML, Javascript and CSS.
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":
Our Jenkins jobs are configured to deploy to Nexus. There, you can find both the source code and the artifacts produced from the 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.
Resources paragraph above)mvn clean packagerator-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.
TODO: Describe the npm and gulp command etc
Resources paragraph above.)npm install./dist/index.html to launch Swagger UI in a browserrator-selfcare-rest-api .war file (either from Jenkins/Nexus, see Resources, or by building the .war yourself, see Build).dist folder (either from Github, or from our own repositories, see Resources. Or by building the project yourself, see Build).webapps directory and (re-)start the Tomcat application. You probably want to rename the dist folder to swagger-ui.
In your browser, enter the URL:
http://<Swagger server and port>/<base-path>/?url=http://<REST server and port>/<base-path>/api/swagger.json |
You should now see a list of the resources available on the REST server.
If both the Swagger UI and the REST application has been deployed to the same Tomcat, and if Tomcat's default "base path to web-app configuration" has not been overwritten, the URL to call may look like this:
http://localhost:8080/swagger-ui/?url=http://localhost:8080/rator-selfcare-rest-api/api/swagger.json |
If you get an error response from the server, try pin pointing the problem:
swagger-ui" if you have followed the installation steps and if the default Tomcat behavior has not been modified. If you get a 404 server error, see step 3.http://<REST server and port>/<base-path>. This should show you the index.html page, which is (currently) a (very) short text stating that you have reached the RESTful webservice. If you get a 404 error response from the server, see step 3.webapps folder. The is called the context. Unless you specify otherwise, the base path is the name of the given web application's main folder. If you get a 404 error response from the server, you should investigate if Tomcat's default base path/context configuration has been overwritten, and with which values. This is general Tomcat configuration, and as such outside the scope of this documentation.A brief remark on Tomcat's base path:
Your Tomcat installation's server.xml file will sometimes specify a base path for the REST project in a <context.../> tag.
<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"/> |
If the Tomcat's server.xml file had a <Context/> tag like the above, where the base path for the rator-selfcare-rest-api is set to the empty string, the project would be available at http://localhost:8080/rator-selfcare-rest-api/api/<SOME RESOURCE>.
When deploying from Eclipse, such entry might have been added automatically. Configuring the context in the server.xml seems to be discouraged by various online sources.
If 404 errors are returned from the server, when accessing the deployed services, you must either modify the base path, or modify the URL accordingly. If you are deploying from Eclipse, you may want to specify the base path on the modules subpane of the server pane.