TopStack Deployment Instance Setup

A TopStack instance requires Tomcat, access to Chef, and some local configuration files to run correctly. The following steps will configure an instance to receive TopStack.

1. Install Tomcat 7 and the admin manager by downloading the binary distribution. Download an appropriate Tomcat from the Tomcat website on the instance. Simply untar the contents of the tar file into /var/lib directory (Run "tar xvf apache-tomcat-7.*.tar.gz -C /var/lib"). Now you have /var/lib/apache-tomcat-7.x.yz directory. Make a softlink /var/lib/tomcat to this directory (Run "ln -s /var/lib/apache-tomcat-7.0.37/ /var/lib/tomcat"). Feel free to test Tomcat 7 and see if it runs before proceeding to the next step.

   -or-

   Use apt (if on a modern Ubuntu):

    sudo apt-get install tomcat7 tomcat7-admin
   

   You will also need to create a directory named ".mule" in the tomcat home (or /var/lib/tomcat7) and ensure it's owned by Tomcat

   sudo mkdir /var/lib/tomcat/.mule

   sudo chown tomcat7:tomcat7 /var/lib/tomcat/.mule

2. Now install unzip through apt-get.

   sudo apt-get install unzip
   

3. Copy the tough-resources-config.zip from a jenkins build environment, or scp the file if you built it locally. This file can be found under the TopStackResources project, under "build/lib" after a successful build.

4. You'll need to unzip tough-resources-config.zip into a config directory. This directory be supplied with a TOUGH_CONFIG_DIR env variable. Also create a "keys" directory and "tmp" directory under /var/lib/tomcat7/tough.

    scp ${TOPSTACK}/TopStackResources/build/lib/tough-resources-config.zip ${INSTANCE_IP}/tmp
    [ on the instance ]
    sudo mkdir -p /var/lib/tomcat7/tough
    sudo unzip /tmp/tough-resources-config.zip -d /var/lib/tomcat7/tough/config
    sudo mkdir /var/lib/tomcat7/tough/keys
    sudo mkdir /var/lib/tomcat7/tough/tmp
   

5. Install chef-client and knife on the instance. Follow the instruction on Chef Installation for Ubuntu/Debian.

6. You need to set hostname to the instance, and configure chef-client and knife now. You will have to have a chef account for the chef server that is controlling your cloud environment. Create a new chef client and give the hostname of the instance as client name. Also make sure to check the "Admin" box to enable this chef client to run in administer mode. This is essential for knife bootstrap functionality to add a role, etc. When you successfully create the client, you should get a public key and a private key. Copy the private key and save it into client.pem. For the default chef-client setting, you can place the client.pem under /etc/chef directory.

    cat > /etc/chef/client.pem
    [ paste key ] + Ctrl+D
   

   Create a custom chef directory under your home directory (e.g. /root). Create /root/.chef directory, and create knife.rb file there. This file defines knife behavior. Below is an example knife.rb:

    log_level            :info
    log_location         STDOUT
    node_name           'instance.example.com'
    cache_type          'BasicFile'
    cache_options( :path => "/root/.chef/checksums" )
    client_key             "/etc/chef/client.pem"
    chef_server_url    "http://{YOUR_CHEF_SERVER}:4000"
    validation_key      "/etc/chef/validation.pem"
    validation_client_name "chef-validator"
   

   At this point, you can call simple knife commands such as "knife node list", but you cannot bootstrap an instance till you get the validation.pem in /etc/chef as well. You can obtain the validation pem from your chef server. scp /etc/chef/validation.pem into your instance. Place this pem file under /etc/chef of your deployment instance.

    # Example:
    ssh [email protected]
    [ on chef server ]
    sudo cp /etc/chef/validation.pem /tmp
    sudo chmod 777 /tmp/validation.pem
    exit
    [ on deployment instance ]
    scp [email protected]:/tmp/validation.pem /etc/chef/validation.pem
    chmod 600 /etc/chef/validation.pem 
   

7. Now we will modify the Tomcat server configuration. We will start by setting environment variables. Typically these environment variables can be set in a file called "setenv.sh" in the Tomcat bin directory, and Tomcat server incorporate the values. Next lines show an example of session to create the setenv.sh file. Assuming we want to deploy to 192.168.1.50:

    cd /usr/share/tomcat7/bin
    cat > setenv.sh 
    CATALINA_OPTS="-Xms128m -Xmx768m -XX:PermSize=256m"
    # TopStack specific variables
    TOUGH_HOME=/var/lib/tomcat7/tough
    TOUGH_CONFIG_DIR=/var/lib/tomcat7/tough/config
    USE_IP_FOR_INSTANCE=no
    YUMHOST=any-value
    CHEF_USER_ID=instance.example.com
    CHEF_PRIVATE_KEY=/etc/chef/client.pem
    CHEF_API_URL=http://chef.example.com:4000
    CHEF_IP=192.168.1.50
    CHEF_SERVER=chef.example.com
    CHEF_ENV=production
    DOTCHEF_DIR=/root
    KEYS_DIR=/var/lib/tomcat7/tough/keys
    FQDN_DOMAIN=example.com
    TRANSCEND_URL=http://192.168.1.50/ASInternal
    SERVLET_URL=http://192.168.1.50:8080/RDSQuery
    export TOUGH_HOME TOUGH_CONFIG_DIR USE_IP_FOR_INSTANCE YUMHOST CHEF_USER_ID CHEF_PRIVATE_KEY CHEF_API_URL CHEF_IP CHEF_SERVER DOTCHEF_DIR CHEF_ENV KEYS_DIR FQDN_DOMAIN TRANSCEND_URL SERVLET_URL JAVA_OPTS
   
    [ Ctrl+D ]
   

8. That's all that's required for Tomcat! Ensure the deployment instance can access the MySQL database and deploy TopStack wars as necessary.