Deploy Semarchy xDM Using the Tomcat Manager

Owned by Anna Rider (Deactivated)
Last updated: Jun 05, 2019 by Peter Tse

Overview

This page guides a new Semarchy administrator on how to deploy Semarchy xDM using the Tomcat Manager interface. It is useful for upgrading to new versions of xDM (it applies equally well to Semarchy Convergence 3.x). 

Prerequisite: Tomcat is already installed as the application server. The admin user who will deploy the app has the role manager-gui (you set the role in authorization step, most likely tomcat-users.xml). The admin user is most likely semadmin.

Steps


  1. Download the xDM - Server Installation Version from Semarchy's download page.
  2. Back up your semarchy.xml file. Back up any other files you have configured, eg. web.xml in the WEB-INF folder. This step is critical. When you have already deployed Semarchy on Tomcat before, once you undeploy, you will lose all your server configurations.
  3. Upload the server installation files to the tmp folder in the Windows or Linux server, e.g. /tmp
    1. Make sure you have the semarchy.war file and your backed up version of semarchy.xml in the /tmp folder. Don't use the generic semarchy.xml or you will lose your configurations.
    2. If you need help with how to get the Semarchy server installation files into the cloud (into EC2 machine), read this guide.
  4. Use the Tomcat Manager app to perform the upgrade
    1. Go to Tomcat Manager. You can access 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
    2. Log in with your admin username and password.
    3. Stop the semarchy application - 
      OK - Stopped application at context path /semarchy
    4. Undeploy the semarchy application - 

      OK - Undeployed application at context path /semarchy


    5. Use the option Deploy directory or WAR file located on server
      1. 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

      3. Click Deploy
      4. Note: Using a context path of /semarchy means the application will be deployed and available at http://localhost/semarchy.
    1. 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: 
      1. The Semarchy WAR file size is too large for the upload. It fails the file size permitted by Tomcat. 
      2. Even if you get around the file size limits, when you deploy with a WAR file upload, Tomcat will not use the semarchy.xml file as the context.xml file. You will see an error after deployment and the Semarchy application will be unavailable. 
  5. 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’
  6. Related articles: