Deploy Instructions

Owned by bcarlsen (Unlicensed)
Last updated: Aug 31, 2016

Overview

Describes how to set up and deploy the application to the umls.terminology.tools server.

Diagram

Details

  1. Log into the server a.terminology.tools or b.terminology.tools
    1. You'll need to be able to sudo su - to root and ec2-tomcat.

  2. Install and configure software as root (nginx, tomcat7 (and webapps), mysql-server-5.5 (and client), Java/jdk (including devel), maven, git, svn, etc.

    1. Edit the /etc/init.d script to comment out the top part that forces running as root

    2. Edit the /etc/init.d script to use this so the ec2-user can write the pid file:

       

      CATALINA_PID="/var/lib/tomcat7/$NAME.pid"
      # also change all instances of /var/run to /var/lib/tomcat7

    • Set permissions of the tomcat installation to the "ec2-tomcat"user:

       

      # for each linked directory in /usr/share/tomcat7 (and /var/log/tomcat7)
      chown -R ec2-tomcat $dir
      chgrp -R ec2-user $dir
       
       
      Edit /etc/init.d/tomcat7 to use the following
      * TOMCAT_USER=ec2-tomcat
      * TOMCAT_GROUP=ec2-user
      * Change all occurences of the .pid file to "/var/lib/tomcat7/tomcat7.pid"
       
      Also edit /etc/tomcat7/tomcat7.conf
      * CATALINA_PID=/var/lib/tomcat7/tomcat7.pid
      * TOMCAT_USER=ec2-tomcat
      * TOMCAT_GROUP=ec2-user
       
       
      Make sure all the "chown" commands in the /etc/init.d/tomcat7 script change to group to $TOMCAT_GROUP

       

      NOTE: the tomcat user can start/stop the server with "/usr/sbin/tomcat7 start/stop".
      HOWEVER: if the process was started by root, it will likely have to be killed by root first..  we're working on this. 

       

  3. Tomcat must be configured to pass "run.config.umls" environment variable to the application
    1. One way to do this is to invoke the java command with -Drun.config.umls=~/config/config.properties
      (e.g. edit this in /usr/share/tomcat7/conf/tomcat7.conf and add to JAVA_OPTS)
    2. Also add -Xmx2500M to JAVA_OPTS in the tomcat startup script.
    3. NOTE: development environments must also be configured as such

  4. Tomcat must be configured to support POST requests of size > 2MB
    1. Edit server.xml and add  maxPostSize="50000000" to each <Connector> element.

  5. Tomcat must be configured to support following of links.  Make sure any Context tags in the configuration contain  allowLinking="true".
    1. Edit context.xml to add this parameter to the Context tag.

  6. To enable tomcat manager, add this to tomcat-users.xml file:

     

    <role rolename="manager-gui" />
    <user name="tomcat" password="********" roles="manager-gui" />
    <role rolename="protected" />
  7. Nginx Configuration
    1. Install the SSL keys as root in the appropriate places (if SSH needed)
    2. Add a file "snomed.term-server.com.conf" to /etc/nginx/conf.d

    3. Add a Valve to tomcat to handle proxy headers:

       

      <Valve className="org.apache.catalina.valves.RemoteIpValve"
             remoteIpHeader="x-forwarded-for"
             remoteIpProxiesHeader="x-forwarded-by"
             protocolHeader="x-forwarded-proto"/>
    4. Edit /etc/nginx/nginx.conf and add "client_max_body_size 50M;" to the "http" context.
    5. /etc/nginx/nginx.conf contains the master configuration - see for details
    6. For more info click here
       

  8. MySQL Configuration - /etc/mysql/my.cnf OR "%PROGRAMDATA%\MySQL\MySQL Server 5.6\my.ini"

    1. When configuring the database URL in config.properties, use ?autoconnect=true to avoid connection issues

    2. Also (as root) edit the my.cnf/ini file for your platform and add this to the mysqld section:

       

      [mysqld]
      ...
      wait_timeout = 230400
      interactive_timeout = 230400
      max_allowed_packet = 4194304

    3. It may also be worth considering using the innodb table per file option:

       

      [mysqld]
      ...
      innodb_file_per_table

       

      This is useful to better manage the overall size of the database because individual tables can then be optimized rather than having to dump/reload the entire database.

    4. Consider other optimizations to mysql parameters (e.g. http://www.percona.com/blog/2014/01/28/10-mysql-settings-to-tune-after-installation/).

       

  9. As the MySQL root user, create an OTF user with the mysql client:

     

    CREATE USER 'otf'@'localhost' IDENTIFIED BY 'otfpwd';
GRANT ALL privileges ON *.* TO 'otf'@'localhost';

  10. As the MySQL root user, create a database in the mysql client:

     

    CREATE DATABASE umlsdb
  DEFAULT CHARACTER SET utf8
  DEFAULT COLLATE utf8_bin;
GRANT ALL ON umlsdb.* TO 'otf';

  11. Create "code", "config", and "data" directories

    1. ~/code - for the code

    2. ~/data - for the data files (only needed on initial load)

    3. ~/config - for the configuration files and configurable admin scripts:

       

      cd
      mkdir code
      mkdir data
      mkdir config

  12. Get code:

  13. Prepare the environment (set your shell up with these ENV variables):

     

    JAVA_HOME=/usr/lib/jvm/jre-1.7.0-openjdk.x86_64
    MAVEN_OPTS="-XX:MaxPermSize=512m -Xmx3000M"

     



  14. Build all of the code, making sure to choose the correct "config.artifactId" for your environment.  Shown is "prod" configuration:

     

    cd ~/code
    mvn -Dconfig.artifactId=term-server-config-prod clean install

  15. Prepare the data:

     

    cd ~/data
    unzip ~/code/config/term-server-config.*.zip

  16. Prepare the tomcat indexes location:

     

    # To clean up the indexes do this (as root)
    /bin/rm -rf /var/lib/tomcat7/indexes/umls
    mkdir /var/lib/tomcat7/indexes/umls
    chmod -R ga+rwx /var/lib/tomcat7/indexes/umls
    chown -R ec2-tomcat:ec2-user /var/lib/tomcat7/indexes/umls
      
    # Ensure the config.properties file used to run the application has this setting
    hibernate.search.default.indexBase=/var/lib/tomcat7/indexes/umls

  17. Unpack the config artifact corresponding to your environment The example shown below is for "prod".

     

    cd ~/config
    unzip ~/code/config/prod/target/term-server-config-prod.*.zip

  18. Edit the configuration file and scripts.

    1. Edit config.properties and replace the "EDIT_THIS" entries with real values (mostly passwords, etc).

    2. Edit the mail notification settings to list email addresses of those admins or maintenance staff that should be notified of errors and/or automation outcomes.

    3. Edit the scripts in bin/ as needed for this environment (default setup requires no changes).|
       

  19. Edit the load script for your environment. Run it to load the data:

     

    cd ~/config/bin
    chmod 775 *sh
    ./load.csh >&! load.log

  20. Deploy war:

     

    /bin/cp -f ~/code/rest/target/term-server-rest*war /var/lib/tomcat7/webapps/term-server-rest.war

  21. Start service:

     

    service tomcat7 start

  22. Run the integration tests (only do this if you know what you're doing):

     

    cd
    cd code/integration-test
    mvn -DskipTests=false -Drun.config.umls.test=~/config/config-test.properties test
  • n/a