In this post let us see how to setup a secondary Tomcat instance. Actually the same method can be used to setup any number of Tomcat instances on a single server as Tomcat is very much capable of running multiple instances in parallel and is only restricted by the available memory and cpu of the server.
This is the first post to start honoring the promise we have made in the About section of our blog. That means this blog is going to provide you source code along with explanation.
The main intention of having secondary instance of Tomcat on the same machine is to allow "Zero Downtime Deployment of New Application Version". The method described here is not specific to Amazon Elastic Beanstalk Environment though that's what we use to run our website hudku.com which is a Tomcat application. The method and scripts provided here can be used on any Linux machine running a tomcat application.
The steps involved are
Pre-Deployment
Deployment
Post-Deployment
According to the way I have designed it, I ended up with a collection of 4 linux bash scripts.
tomcat-setup-secondary.sh - Setup script that needs to be run only once.
tomcat-copy-to-secondary.sh - Script to copy existing web application available at primary instance to secondary instance.
tomcat-start-secondary.sh - Script to start secondary tomcat instance.
tomcat-stop-secondary.sh - Script to stop secondary tomcat instance.
In this post we are going to analyze the first script which is the setup script. Here we go.
The script needs two environment variables providing the names of the primary and secondary instances. For example if your primary instance name is "tomcat7" and the secondary instance name is "my-app-secondary" then make them available using following commands.
export TOMCAT_PRIMARY_INSTANCE_NAME="tomcat7"
export TOMCAT_SECONDARY_INSTANCE_NAME="my-app-secondary"
On our machine the location of our tomcat applications is "/usr/share/". You will have to edit the scripts if have to change them. If you are using Elastic Beanstalk, then that is the default location.
Now we are coming to my favourite line in this entire script.
Now how do we invoke the same script with a different name because the secondary instance has to have its own name "my-app-secondary". This is where the beauty lies which I admired and hence is my comment about it being my favourite line in this script. All we have to do is create a Linux soft link to that script file which is what the line does. It creates a soft link called "my-app-secondary" and links to that main script file. Then instead of invoking the main script file, we invoke it through this link and hence the same script gets invoked by a different name chosen by us. By creating a link we did not duplicate the code.
After working with bash scripts for a while now, I have come to know that bash programmers do this all the time. But as I was seeing this for the very first time I was elated. I hope you agree that when we experience anything wonderful for the very first time, its pleasure is unmatched.
But having a facility and knowing about it is just not enough. Using it at the most appropriate place is what is most important and hence join me in appreciating the architect who provided this script for us. Also let us use this moment to take a pause and to appreciate from the bottom of our hearts, the efforts of Apache Tomcat team as well as all the contributors of Apache Software Foundation who have been delighting us with their entire range of open source software.
As we have now created a link using the name of our secondary instance, the bulk of the job is done. Next is to adjust the configuration settings.
For our secondary instance instead of having two files, we can get away by having just one file /etc/sysconfig/my-app-secondary as that is the name we have used for our secondary instance. That's why the order is important in the above code snippet. First we copy the contents of the base configuration file and then append to it the contents of the instance specific configurations. Then using the Linux "sed" command we substitute all occurrences of the primary instance name with the name of the secondary instance.
Next we need to setup the tomcat instance directory /usr/share/my-app-secondary in identical fashion when compared to the directory of the primary instance /usr/share/tomcat7. Basically we need to create four entries viz., "logs", "temp", "work" and "lib".
In our machine the primary instance has directores /var/cache/tomcat7/temp and /var/cache/tomcat7/work and in the directory /usr/share/tomcat7/ temp and work are soft links to those directories in /var/cache/. Then "lib" is a softlink to a tomcat installation folder containing the library files.
We also create our create temp and work directories in /var/cache/my-app-secondary/ folder, set up temp and work as softlinks to them in the folder /usr/share/my-app-secondary/ and then copy the softlink "link" as is from the primary instance folder to the secondary instance folder.
Finally set the appropriate permissions for all the files and folder present in /usr/share/my-app-secondary so that tomcat process can access them.
That's it. Setup of Tomcat secondary instance is complete. In the next posts we shall get on with operating the tomcat secondary instance.
The full script contains few lines in the beginning which I did not discuss here as I wanted to just focus on the topic on hand without any deviation. Those lines should be obvious and I shall talk about them along with all the things related to them in my future posts.
We are using Syntax Highlighter developed by Alex Gorbatchev to display the source code and we would like to take this opportunity to thank him for his efforts. You can double click anywhere on the code to select the entire code so that it can be copied to the clipboard.
Here is the full source code of "tomcat-setup-secondary.sh".
This is the first post to start honoring the promise we have made in the About section of our blog. That means this blog is going to provide you source code along with explanation.
The main intention of having secondary instance of Tomcat on the same machine is to allow "Zero Downtime Deployment of New Application Version". The method described here is not specific to Amazon Elastic Beanstalk Environment though that's what we use to run our website hudku.com which is a Tomcat application. The method and scripts provided here can be used on any Linux machine running a tomcat application.
The steps involved are
Pre-Deployment
- Bring up secondary tomcat instance of web application.
- Test that secondary instance has come up successfully.
- Internally redirect all the ports of primary instance to ports used by secondary instance.
- Test that redirection is indeed successful.
Deployment
- Deploy new application version to the primary instance.
Post-Deployment
- Check primary instance is running properly after the deployment of the new version of the application.
- Delete all the internal port redirections we did earlier so that primary instance listening at default ports starts handling all requests.
- Shut down the secondary instance.
According to the way I have designed it, I ended up with a collection of 4 linux bash scripts.
tomcat-setup-secondary.sh - Setup script that needs to be run only once.
tomcat-copy-to-secondary.sh - Script to copy existing web application available at primary instance to secondary instance.
tomcat-start-secondary.sh - Script to start secondary tomcat instance.
tomcat-stop-secondary.sh - Script to stop secondary tomcat instance.
In this post we are going to analyze the first script which is the setup script. Here we go.
tomcatPrimaryInstanceName="$TOMCAT_PRIMARY_INSTANCE_NAME" tomcatSecondaryInstanceName="$TOMCAT_SECONDARY_INSTANCE_NAME" tomcatPrimaryInstanceDir="/usr/share/$tomcatPrimaryInstanceName" tomcatSecondaryInstanceDir="/usr/share/$tomcatSecondaryInstanceName" The script needs two environment variables providing the names of the primary and secondary instances. For example if your primary instance name is "tomcat7" and the secondary instance name is "my-app-secondary" then make them available using following commands.
export TOMCAT_PRIMARY_INSTANCE_NAME="tomcat7"
export TOMCAT_SECONDARY_INSTANCE_NAME="my-app-secondary"
On our machine the location of our tomcat applications is "/usr/share/". You will have to edit the scripts if have to change them. If you are using Elastic Beanstalk, then that is the default location.
Now we are coming to my favourite line in this entire script.
ln -s /etc/init.d/$tomcatPrimaryInstanceName /etc/init.d/$tomcatSecondaryInstanceName
In our server the tomcat installation has created a file tomcat7 in the directory /etc/init.d/ which is the main script file to start or stop tomcat. The designer of this script has used the name by which this script gets invoked as the name of the tomcat instance to be started or stopped. By default in our machine the script file is called "tomcat7" and hence that becomes the name of our primary instance.Now how do we invoke the same script with a different name because the secondary instance has to have its own name "my-app-secondary". This is where the beauty lies which I admired and hence is my comment about it being my favourite line in this script. All we have to do is create a Linux soft link to that script file which is what the line does. It creates a soft link called "my-app-secondary" and links to that main script file. Then instead of invoking the main script file, we invoke it through this link and hence the same script gets invoked by a different name chosen by us. By creating a link we did not duplicate the code.
After working with bash scripts for a while now, I have come to know that bash programmers do this all the time. But as I was seeing this for the very first time I was elated. I hope you agree that when we experience anything wonderful for the very first time, its pleasure is unmatched.
But having a facility and knowing about it is just not enough. Using it at the most appropriate place is what is most important and hence join me in appreciating the architect who provided this script for us. Also let us use this moment to take a pause and to appreciate from the bottom of our hearts, the efforts of Apache Tomcat team as well as all the contributors of Apache Software Foundation who have been delighting us with their entire range of open source software.
As we have now created a link using the name of our secondary instance, the bulk of the job is done. Next is to adjust the configuration settings.
/bin/cp -f /etc/$tomcatPrimaryInstanceName/$tomcatPrimaryInstanceName.conf /etc/sysconfig/$tomcatSecondaryInstanceName cat /etc/sysconfig/$tomcatPrimaryInstanceName >> /etc/sysconfig/$tomcatSecondaryInstanceName sed -i "s/$tomcatPrimaryInstanceName/$tomcatSecondaryInstanceName/g" /etc/sysconfig/$tomcatSecondaryInstanceName In our machine for the default instance the base configuration is provided by the file /etc/tomcat7/tomcat7.conf. Then its settings can be overridden and additional settings can be added by having the file /etc/sysconfig/tomcat7. This is how the main script we discussed above parses these configuration settings.For our secondary instance instead of having two files, we can get away by having just one file /etc/sysconfig/my-app-secondary as that is the name we have used for our secondary instance. That's why the order is important in the above code snippet. First we copy the contents of the base configuration file and then append to it the contents of the instance specific configurations. Then using the Linux "sed" command we substitute all occurrences of the primary instance name with the name of the secondary instance.
Next we need to setup the tomcat instance directory /usr/share/my-app-secondary in identical fashion when compared to the directory of the primary instance /usr/share/tomcat7. Basically we need to create four entries viz., "logs", "temp", "work" and "lib".
# Create the tomcat instance directory rm -rf $tomcatSecondaryInstanceDir mkdir -p $tomcatSecondaryInstanceDir chmod 775 $tomcatSecondaryInstanceDir # Create the logs directory mkdir -p $tomcatSecondaryInstanceDir/logs # Create temp and work directories mkdir -p /var/cache/$tomcatSecondaryInstanceName/temp mkdir -p /var/cache/$tomcatSecondaryInstanceName/work chmod -R 770 /var/cache/$tomcatSecondaryInstanceName chown -R tomcat:tomcat /var/cache/$tomcatSecondaryInstanceName # Create the links for temp and work directories ln -s /var/cache/$tomcatSecondaryInstanceName/temp $tomcatSecondaryInstanceDir/temp ln -s /var/cache/$tomcatSecondaryInstanceName/work $tomcatSecondaryInstanceDir/work # Copy the "lib" link from the primary instance cp -d $tomcatPrimaryInstanceDir/lib $tomcatSecondaryInstanceDir/ # Set the directory and file permissions chmod -R 777 $tomcatSecondaryInstanceDir/* chown -R tomcat:tomcat $tomcatSecondaryInstanceDir/* "logs" is a simple directory in which tomcat log files reside.In our machine the primary instance has directores /var/cache/tomcat7/temp and /var/cache/tomcat7/work and in the directory /usr/share/tomcat7/ temp and work are soft links to those directories in /var/cache/. Then "lib" is a softlink to a tomcat installation folder containing the library files.
We also create our create temp and work directories in /var/cache/my-app-secondary/ folder, set up temp and work as softlinks to them in the folder /usr/share/my-app-secondary/ and then copy the softlink "link" as is from the primary instance folder to the secondary instance folder.
Finally set the appropriate permissions for all the files and folder present in /usr/share/my-app-secondary so that tomcat process can access them.
That's it. Setup of Tomcat secondary instance is complete. In the next posts we shall get on with operating the tomcat secondary instance.
The full script contains few lines in the beginning which I did not discuss here as I wanted to just focus on the topic on hand without any deviation. Those lines should be obvious and I shall talk about them along with all the things related to them in my future posts.
We are using Syntax Highlighter developed by Alex Gorbatchev to display the source code and we would like to take this opportunity to thank him for his efforts. You can double click anywhere on the code to select the entire code so that it can be copied to the clipboard.
Here is the full source code of "tomcat-setup-secondary.sh".
#!/bin/bash # Execute "export DEBUG=1" to debug this script. # Set value to 2 to debug this script and the scripts called within this script. # Set value to 3,4,5 and so on to increase the nesting level of the scripts to be debugged. [[ $DEBUG -gt 0 ]] && set -x; export DEBUG=$(($DEBUG - 1)) # # Does one time setting necessary to setup a secondary tomcat instance. # # include all the utility scripts source $ELASTICBEANSTALK_APP_SCRIPT_DIR/include/include.sh tomcatPrimaryInstanceName="$TOMCAT_PRIMARY_INSTANCE_NAME" tomcatSecondaryInstanceName="$TOMCAT_SECONDARY_INSTANCE_NAME" tomcatPrimaryInstanceDir="/usr/share/$tomcatPrimaryInstanceName" tomcatSecondaryInstanceDir="/usr/share/$tomcatSecondaryInstanceName" # Create a link to the existing init script file. The name used for the link becomes the name of the tomcat instance if ([ ! -e /etc/init.d/$tomcatSecondaryInstanceName ]) then ln -s /etc/init.d/$tomcatPrimaryInstanceName /etc/init.d/$tomcatSecondaryInstanceName chmod 755 /etc/init.d/$tomcatSecondaryInstanceName fi # Copy the contents of the main configuration and the configuration file in /etc/sysconfig and substitute the instance name /bin/cp -f /etc/$tomcatPrimaryInstanceName/$tomcatPrimaryInstanceName.conf /etc/sysconfig/$tomcatSecondaryInstanceName cat /etc/sysconfig/$tomcatPrimaryInstanceName >> /etc/sysconfig/$tomcatSecondaryInstanceName sed -i "s/$tomcatPrimaryInstanceName/$tomcatSecondaryInstanceName/g" /etc/sysconfig/$tomcatSecondaryInstanceName if [ -e $tomcatSecondaryInstanceDir ]; then echo "$tomcatSecondaryInstanceDir folder already exists. Nothing more to do." exit 0 fi # Create the tomcat instance directory rm -rf $tomcatSecondaryInstanceDir mkdir -p $tomcatSecondaryInstanceDir chmod 775 $tomcatSecondaryInstanceDir # Create the logs directory mkdir -p $tomcatSecondaryInstanceDir/logs # Create temp and work directories mkdir -p /var/cache/$tomcatSecondaryInstanceName/temp mkdir -p /var/cache/$tomcatSecondaryInstanceName/work chmod -R 770 /var/cache/$tomcatSecondaryInstanceName chown -R tomcat:tomcat /var/cache/$tomcatSecondaryInstanceName # Create the links for temp and work directories ln -s /var/cache/$tomcatSecondaryInstanceName/temp $tomcatSecondaryInstanceDir/temp ln -s /var/cache/$tomcatSecondaryInstanceName/work $tomcatSecondaryInstanceDir/work # Copy the "lib" link from the primary instance cp -d $tomcatPrimaryInstanceDir/lib $tomcatSecondaryInstanceDir/ # Set the directory and file permissions chmod -R 777 $tomcatSecondaryInstanceDir/* chown -R tomcat:tomcat $tomcatSecondaryInstanceDir/* echo "Success. Secondary tomcat instance $tomcatSecondaryInstanceName has been setup successfully."