Saturday, August 25, 2012

Build and Install Tomcat 7 From Source on Mac OS X

Before you begin:

The instructions below are to be followed at your own discretion and at your own risk. It is up to you to execute the commands outlined  in this tutorial and is strongly advised that if you do not understand the implications or repercussions one or more of the following instructions, that you do not proceed.

Note that I am on Mac OS X Snow Leopard (version 10.5.8). If you are on a different version of OS X, please consult the documentation specific to your version prior to following this tutorial.

You must have both Java and Apache Ant installed to complete this tutorial. The instructions in this tutorial assume that Ant is located at /usr/share/ant and Java is located at /Library/Java/Home. If they are in different locations on your machine, please make adjustments accordingly.

These instructions also assume the latest release of Tomcat as of the time of this writing, which is version 7.0.29. If you want to install a different version of Tomcat, please consult the Apache Tomcat documentation.

Some of the lines below require altering the ~/.bash_profile file. Your machine may require that you alter the ~/.bash_login file or the ~/.profile file instead. See this page on stack overflow for some information on which one you may want to edit. Make sure that you are comfortable editing these files before you proceed and that you understand the consequences.

All the commands below are intended to be executed in a terminal window and it is assumed that you are using the default bash terminal for Mac OS X. If you are using another terminal, it is up to you to adjust the commands to fit your terminal.

If, at any time, you need to know what your current directory is, type pwd (print working directory) into the the terminal.

Now, let's get started...

  1. See if you have the JAVA_HOME and ANT_HOME environment variables set. If you do, the following command should print out the directories that the variables are pointed to:
    echo $JAVA_HOME && echo $ANT_HOME If no directory path is printed out for one, or both, of these, then follow the instructions below to set the JAVA_HOME and ANT_HOME environment variables.

    The following commands will set the variables for your current command-line (terminal) session: export JAVA_HOME=/Library/Java/Home
    export PATH="$JAVA_HOME/bin:$PATH"
    export ANT_HOME=/usr/share/ant
    export PATH="$ANT_HOME/bin:$PATH"
    And these commands will make sure these variables are available for future terminal sessions: echo 'export JAVA_HOME=/Library/Java/Home' >> ~/.bash_profile
    echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.bash_profile
    echo 'export ANT_HOME=/usr/share/ant' >> ~/.bash_profile
    echo 'export PATH="$ANT_HOME/bin:$PATH"' >> ~/.bash_profile
  2. Now, let's make some directories to download the Tomcat source code into. sudo mkdir /Library/Tomcat && cd /Library/Tomcat
    sudo mkdir src && cd src
    sudo mkdir src-downloads
  3. Download the Tomcat 7 source code into the current directory /Library/Tomcat/src. sudo wget
  4.  Expand the tar.gz file you just downloaded into the current directory, this will create a new directory called apaache-tomcat-7.0.29-src.
    sudo tar -zxvf apache-tomcat-7.0.29-src.tar.gz
  5. Change directories into the new directory. cd apache-tomcat-7.0.29-src
  6. Create a file. sudo touch
  7. Now open the file in your preferred editor and add the following line to it to tell Ant which directory to download dependencies into: base.path=/Library/Tomcat/src/src-downloads
  8. Run Ant on the current directory (which should be /Library/Tomcat/src/apache-tomcat-7.0.29-src). sudo ant
  9. Once Ant completes successfully, it will have created a folder named build in the directory /Library/Tomcat/src/output.
  10. We want to move this build directory up to the /Library/Tomcat directory and rename it something more relevant. sudo mv output/build /Library/Tomcat/apache-tomcat-7.0.29
  11. Change directories back to the /Library/Tomcat directory. cd ../../
  12. Create a symbolic link called Home and point it to the new tomcat build. sudo ln -svhf apache-tomcat-7.0.29 Home
  13. Go into the bin folder, remove any Windows .bat files and give execute permissions to the shell scripts. cd Home/bin
    sudo rm *.bat
    sudo chmod 755 *.sh
  14. Create a CATALINA_HOME environment variable and add it to the PATH for your current terminal session. export CATALINA_HOME=/Library/Tomcat/Home
  15. Now, add CATALINA_HOME for future terminal sessions. echo 'export CATALINA_HOME=/Library/Tomcat/Home' >> ~/.bash_profile
    echo 'export PATH="$CATALINA_HOME:$PATH"' >> ~/.bash_profile
  16. Add aliases for the Tomcat startup and shutdown scripts to the current terminal session. alias start-tomcat="sudo $CATALINA_HOME/bin/"
    alias stop-tomcat="sudo $CATALINA_HOME/bin/"
  17. Add the above aliases in ~/.bash_profile so they are available for all future terminal sessions as well. echo 'alias start-tomcat="sudo $CATALINA_HOME/bin/"' >> ~/.bash_profile
    echo 'alias stop-tomcat="sudo $CATALINA_HOME/bin/"' >> ~/.bash_profile
  18. Add roles and users to /Library/Tomcat/Home/conf/tomcat-users.xml.
  19. Start up Apache Tomcat. start-tomcat
  20. Browse to http://localhost:8080 in your browser to see the Tomcat home page.
  21. Shutdown Apache Tomcat. stop-tomcat
If you are interested in running Tomcat on system start-up, see Run Tomcat as a Start-Up Service Daemon in Mac OS X. Thanks for reading!