This article guides a Semarchy Administrator on how to use the Tomcat Manager interface to deploy Semarchy xDM. This applies to install xDM and to upgrade to new versions of xDM.
Background
The Tomcat Manager is a web application bundled with the Tomcat server and provides the basic functionality needed to manage deployed web applications. The software program Tomcat Manager is integrated within the Tomcat server. It is installed in the context path /manager and provides the basic features for managing Web applications running on tomcat. In apache tomcat versions 8.5 and above, tomcat manager it’s only accessible using the localhost URL.
Steps
1. Download the xDM - Server Installation from Semarchy’s download page.
2. Back up your semarchy.xml file and any other files you have configured, such as the web.xml file in the WEB-INF/ folder. This step is critical. If you have already deployed Semarchy on Tomcat before, once you undeploy, you will lose all your server configurations.
Upload the server installation files to a folder accessible by Tomcat.
On Linux, use: /tmp
On Windows, use: For example C:\Program files\tomcat. (where the tomcat folder is stored on your computer).
3. Use the Tomcat Manager app to perform the upgrade.
a. Go to Tomcat Manager. You can access the Tomcat Manager by going to localhost/manager/html. Substitute localhost for your server’s address if it is hosted in the Cloud, eg. http://ec2-12-34-56-78.us-west-1.compute.amazonaws.com/manager/html
b. Login with your admin username and password.
c. Stop the Semarchy application: A status message appears.
d. Undeploy the Semarchy application: A status message appears.
5. Use the option Deploy directory or WAR file located on the server
a. Type in the context path and use the paths where the semarchy.xml and semarchy.war files are located. For example:
- Context Path (required) : /semarchy
- XML Configuration file URL: /tmp/semarchy.xml
- WAR or Directory URL: /tmp/semarchy.war
b. Click Deploy.
c. Note: Using a context path of /semarchy means the application will be deployed and available at http://localhost/semarchy.
6. Do NOT use the remote client that allows you to upload the WAR file. There are two major reasons you should not use the WAR file to deploy option.
- The Semarchy WAR file size is too large for the upload. It fails the file size permitted by Tomcat.
- Even if you get around the file size limits, when you deploy with a WAR file upload, Tomcat will not use the
semarchy.xmlfile as thecontext.xmlfile. You will see an error after deployment and the Semarchy application will be unavailable.
7. If you are successful, you will see a message output telling you that you have successfully deployed the application: ‘OK – Deployed application at context path /semarchy’
Troubleshooting guide
Problem: You receive a 403 Access Denied error.
Typically, this error occurs when an administrator is attempting to access Tomcat Manager from another machine than the server hosting the Tomcat. By default, Tomcat Manager is configured to only be accessible directly on the Tomcat server. You will need to follow the steps below to enable access to the Tomcat Manager outside of the localhost.
Solution
To access Tomcat Manager outside of the localhost, you need to do the following
- Go to
<TOMCAT_HOME>/webapps/manager/META-INF - Open
context.xmland add the appropriate IP address in the Valve section as below.
Here is an example:
<Valve className="org.apache.catalina.valves.RemoteAddrValve" allow="192\.168\.128\.\d+|127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1" />- Next, go to
conf/folder and opentomcat-users.xmladd a user the manager role. You will use this user to login to the tomcat manager.
<role rolename="manager-gui"/>
<user username="tomcat" password="tomcat" roles="manager-gui"/> <user username="semadmin" password="semadmin" - Save the configuration file and restart the Tomcat.
- Now access your Tomcat Manager and should prompt you to log in.
Note: If you want to access the host manager, you also need to modify the context.xml file for the host-manager.