path: root/en_US.ISO8859-1/articles/java-tomcat/article.sgml

<!-- Copyright (c) 2002, 2003, 2004
     Hiten Pandya <hmp@FreeBSD.org>, Victoria Chan <vkchan@kendryl.net>.
     
     All rights reserved.

     Redistribution and use in source (SGML DocBook) and 'compiled' forms
     (SGML, HTML, PDF, PostScript, RTF and so forth) with or without
     modification, are permitted provided that the following conditions
     are met:

      1. Redistributions of source code (SGML DocBook) must retain the above
         copyright notice, this list of conditions and the following
         disclaimer as the first lines of this file unmodified.

      2. Redistributions in compiled form (transformed to other DTDs,
         converted to PDF, PostScript, RTF and other formats) must reproduce
         the above copyright notice, this list of conditions and the
         following disclaimer in the documentation and/or other materials
         provided with the distribution.

     THIS DOCUMENTATION IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS "AS IS" 
     AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 
     THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
     PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS AND CONTRIBUTORS BE 
     LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
     CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
     SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
     INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
     CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
     ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED 
     OF THE POSSIBILITY OF SUCH DAMAGE.
-->

<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;

<!ENTITY % trademarks PUBLIC "-//FreeBSD//ENTITIES DocBook Trademark Entities//EN">
%trademarks;

<!ENTITY % urls PUBLIC "-//FreeBSD//ENTITIES DocBook URL Entities//EN">
%urls;
<!--
  URL Entities.  These are in place, to allow wrapping long URLs to the 80th
  column.
-->
<!ENTITY wwwurl  "http://www.FreeBSD.org">
<!ENTITY ftpurl  "ftp://ftp.FreeBSD.org">
<!ENTITY sunurl  "http://www.sun.com">
<!ENTITY tomcaturl  "http://jakarta.apache.org/tomcat">

<!-- The Download URL is too long! :-) -->
<!ENTITY tomcat406 "http://jakarta.apache.org/builds/jakarta-tomcat-4.0/release/v4.0.6/bin/">
]>

<article>

  <!-- START of Article Metadata -->
  <articleinfo>
    <title>&java; and Jakarta Tomcat on FreeBSD</title>

    <authorgroup>      
      <author>
	<firstname>Victoria</firstname>
	<surname>Chan</surname>
	<affiliation>
	  <address><email>vkchan@kendryl.net</email></address>
	</affiliation>
      </author>

      <author>
	<firstname>Hiten</firstname>
	<surname>Pandya</surname>
	<affiliation>
	  <address><email>hmp@FreeBSD.org</email></address>
	</affiliation>
      </author>
    </authorgroup>

    <copyright>
      <year>2002</year>
      <year>2003</year>
      <year>2004</year>
      <holder role="mailto:vkchan@kendryl.net">Victoria Chan</holder>
      <holder role="mailto:hmp@FreeBSD.org">Hiten Pandya</holder>
    </copyright>
    
    <pubdate>$FreeBSD$</pubdate> 

    <legalnotice id="trademarks" role="trademarks">
      &tm-attrib.freebsd;
      &tm-attrib.cvsup;
      &tm-attrib.linux;
      &tm-attrib.microsoft;
      &tm-attrib.sun;
      &tm-attrib.general;
    </legalnotice>

    <abstract>
      <para>This document is presented in hopes of making it easier for
	anyone that needs to get &java; up and running on FreeBSD, with the
	least amount of aggravation.  Plan on spending a whole day on such
	a project as it will take time to assemble all the pieces and
	compile them individually, and then as a whole.  It also shows how
	to install the famous Jakarta Tomcat Servlet and &jsp; container on
	the FreeBSD operating system.</para>
    </abstract>
  </articleinfo>
  <!-- END of Article Metadata-->
  
  <sect1>
    <title>Introduction</title>

    <para>The &java; programming language was birthed on <literal>May 23rd
      1995</literal>.  One would expect that after all this time, &java;
      applications would be easy to install and ready to run from a single
      package, or port on FreeBSD, thus making it available for the
      <quote>masses</quote>.  This is not the case, unfortunately, as
      the &java; distribution is held very closely by Sun Microsystems,
      and prohibits re-distribution.  All &java; Applets must be compiled
      from source code, together with the &java; Development Kit from Sun
      Microsystems.  All these ingredients must be blended together in
      the right order, assembled, and compiled by the end user.  With
      such distribution philosophies at heart, it is my opinion that
      &java; will always be developer or hacker use only.  I certainly
      found this to be true when I needed to serve up some
      <filename>.jsp</filename> pages for a client on my web server,
      and needed to get <filename
      role="package">www/jakarta-tomcat4</filename> to work with
      <filename role="package">www/apache13</filename> on my FreeBSD
      system.</para>

    <para>The Tomcat portion of the install is very straight forward, but
      the difficulty I had was getting &java; Development Kit up and
      running for FreeBSD 4.X, as Sun Microsystems only supplies
      Binaries for Linux, &solaris;, and &windowsnt;.  This means that I
      had to compile my own &jdk; for FreeBSD.  I began by searching for
      documentation on the Internet.  I quickly found that there is more
      source code than I need along with patches to the source code, but
      very little documentation of what to do after obtaining
      everything.</para>

    <para>In this article, you will find how to install the &java;
      Development Kit for FreeBSD, and how to get up and running with
      Tomcat.  A <xref linkend="ref"> section is also provided for
      further reading.</para>	
  </sect1>

  <sect1>
    <title>The &java; Environment</title>

    <para>Ensure that you have the current ports collection as
      <command>make</command> it will fail if it attempts to build older
      source.  You can upgrade your entire ports collection by using
      <application>CVSup</application>.  See <ulink
      url="&url.books.handbook;/cvsup.html">Using CVSup</ulink> section
      of the Handbook for more information.  You can also download the
      ports you need manually from <ulink
      url="&ftpurl;/pub/FreeBSD/ports/"></ulink> to
      get you going.</para>

      <note>
	<para>You will need the <literal>Linux Emulation</literal>
	  (Linux-ABI) enabled in your kernel configuration.  Simply add
	  the following option to your kernel configuration file and
	  recompile it.  Instructions for building a kernel can be found
	  in the <ulink url="&url.books.handbook;/index.html">FreeBSD
          Handbook</ulink>.</para>

	<programlisting>options		COMPAT_LINUX</programlisting>

	<para>The above option will add Linux-ABI support to your
	  kernel, when it is recompiled.</para>
      </note>

    <para>The list of dependencies below, are required to be installed
      manually in a certain order.  Dependencies that are automatically
      downloaded are not listed here.</para>

    <itemizedlist>
      <listitem>
	<para><filename role="package">java/jdk13</filename></para>
      </listitem>

      <listitem>
	<para><filename role="package">java/linux-jdk13</filename></para>
      </listitem>
    </itemizedlist>

    <para>You will need to get the following:</para>

    <procedure>
      <step>
	<para>Download <filename>bsd-jdk131-patches-9.tar.gz</filename>
	  from <ulink
	  url="http://www.eyesbeyond.com/freebsddom/java/jdk13.html"></ulink>
	  and place it under <filename>/usr/ports/distfiles</filename>.</para>
      </step>

      <step>
	<para>Next get out your web browser and head on over to
	  <ulink url="http://java.sun.com/j2se/1.3/download-linux.html"></ulink>
	  and find SDK downloads. Click on the <quote>continue</quote>
	  button below <quote>GNUZIP Tar Shell Script</quote>.  Be sure
	  you read every word of the license page before you click on
	  the <quote>Accept</quote> button! You will be brought to a
	  page titled <quote>Download Java(TM) 2 SDK, Standard Edition
	  1.3.1_10</quote>.  Scroll to the bottom and click on the
	  <quote>HTTP download</quote> button.  When the <quote>File
	  Download</quote> box comes up, be sure to click on the
	  <quote>Open</quote> button rather than the <quote>Save</quote>
	  button.  You will be presented with another <quote>File
	  Download</quote> box - this time choose <quote>Save</quote>
	  and you will be able to save
          <filename>j2sdk-1_3_1_10-linux-i386.bin</filename>.
	  Place it in <filename>/usr/ports/distfiles</filename>.</para>
      </step>

      <step>
	<para>Go to <ulink
	  url="http://www.sun.com/software/java2/download.html"></ulink>.
	  In the table under <literal>Produce Description</literal>,
	  named <literal>Java 2 SDK 1.3.1</literal>, go to the
	  right-hand cell and click <quote>download</quote>.  You will
	  be taken to the <quote>Sign On</quote> page, where you must
	  sign in if you already have an account, or register for
	  access.  Once you have signed on, you will be taken to the
	  <quote>Legal</quote> page, where you must accept the license
	  agreement; scroll down (reading the license) and click on the
	  <quote>Continue</quote> button.  Next page, is the
	  <quote>Receipt</quote> page.  This is where you will save your
	  order number.  You will be able to choose the location that is
	  nearest to you.  Click on <quote>Java 2 SDK, Standard Edition,
	  version 1.3.1</quote>.  Save the
	  <filename>j2sdk-1_3_1-src.tar.gz</filename> to the
	  <filename>/usr/ports/distfiles/</filename> directory.</para>	  
      </step>
    </procedure>

    <note>
      <para>It is very important for you to read the License Agreement
	which has been issued by Sun Microsystems Corp.  There are
	several restrictions in place on the use of &java;, which you must
	address. The FreeBSD Project does not take any responsibilities
	for your actions.</para>
      
      <para>Do not discard any of the downloaded files, as they will be
	needed for building some of the native ports for FreeBSD, which
	are discussed later on.</para>
    </note>

    <para>Now that you have assembled all the source files and ports,
      you need to start by building <filename
      role="package">java/linux-jdk13</filename>:</para>

    <screen>&prompt.root; cd /usr/ports/java/linux-jdk13
&prompt.root; make all install clean</screen>

    <para>Once you have built <filename
      role="package">java/linux-jdk13</filename>, you need to test it, to
      make sure it works as intended.  To do that:</para>

    <screen>&prompt.root; cd /usr/local/linux-jdk1.3.1/bin
&prompt.root; ./java -version</screen>

    <para>The output of the above command should be as follows:</para>

    <programlisting>java version "1.3.1_10"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1_10-b02)
Classic VM (build 1.3.1_02-b02, green threads, nojit)</programlisting>

    <para>If you did not get the correct response, you need to:</para>

    <screen>&prompt.root; cd /usr/ports/java/linux-jdk13
&prompt.root; make deinstall</screen>

    <para>And make sure that <filename>/usr/local</filename> does not
      contain a <filename>linux-jdk1.3.1</filename> directory.  If you
      find a fragment of the directory, delete it.  Repeat the
      build and install process for <filename
      role="package">java/linux-jdk13</filename>.</para>

    <para>To make the native <literal>Java Development Kit
      1.3.1</literal> for FreeBSD, do the following:</para>

    <procedure>
      <step>
	<para>Make sure you have the
	  <filename>j2sdk-1_3_1-src.tar.gz</filename> file in your
	  <filename>/usr/ports/distfiles</filename>.  This file is needed
	  for applying the <quote>patch-set</quote> discussed below.</para>
      </step>

      <step>
	<para>You will need to download the <literal>patch set</literal>
	  for building the port.  The patch-set file is called
	  <filename>bsd-jdk131-patches-9.tar.gz</filename>.  You should
	  also make sure the integrity of the files by matching it with
	  the following <acronym>MD5</acronym> checksum.</para>

        <programlisting>
MD5 (bsd-jdk131-patches-9.tar.gz) = 29c83880d3555abcf74fc7df9db1959f</programlisting>

        <para>The patch-set is available from:  <ulink
	  url="http://www.eyesbeyond.com/freebsddom/java/index.html"></ulink></para>
      </step>
    </procedure>

    <para>The last procedure discussed above (building the native
      &jdk;) will take some time.</para>
  </sect1>

  <sect1>
    <title>Jakarta Tomcat Setup</title>

    <sect2>
      <title>Overview</title>

      <para>&java; is becoming an even more popular for making diverse
	and scalable platform independent solutions.  One of the most
	growing needs of &java; is in the <acronym>ASP</acronym> (Application
	Service Provider) market.  &java; serves as the perfect
	solution for these types of markets, with the following
	advantages:</para>

      <itemizedlist>
	<listitem>
	  <para>Platform Independence</para>
	</listitem>

	<listitem>
	  <para>Industry Wide Commitment</para>
	</listitem>

	<listitem>
	  <para>Scalability</para>
	</listitem>

	<listitem>
	  <para>Reliable Performance</para>
	</listitem>

	<listitem>
	  <para>Distributed, Multi-threaded, Secure etc.</para>
	</listitem>
      </itemizedlist>

      <para>A very important and growing technology which has emerged
	from &java; is <acronym>&jsp;</acronym> (&javaserver.pages;).</para>

      <para><acronym>&jsp;</acronym> (&javaserver.pages;) is a server-side
	technology introduced by <literal>Sun Microsystems
	Corp.</literal>, which provides a quick simple way to generate
	dynamic content from within <acronym>HTML</acronym> pages.  It
	uses <acronym>XML</acronym> tags along with &java; scriptlets to
	encapsulate and separate the logic from the design and display.
	When a <acronym>&jsp;</acronym> page is invoked, it is dynamically
	converted into a Servlet and processed by the server to produce
	the resulting <acronym>HTML/XML</acronym> page for the client.
	When <acronym>&jsp;</acronym> is used in conjunction with
	JavaBeans, it is possible to produce very diverse and scalable
	applications, which may be combined with the strength and
	performance of FreeBSD.</para>

      <para><application>Tomcat</application> is an open-source
	implementation of the &java; Servlets and &javaserver.pages;
	technologies, developed under the Jakarta project at the Apache
	Software Foundation.  Tomcat implements a new Servlet framework
	(called Catalina) that is based on completely new architecture
	with the Servlet 2.3 and <acronym>&jsp;</acronym> 1.2
	specifications.  It includes many additional features that make
	it a useful platform for developing and deploying web
	applications and web services.  In a nutshell, Tomcat is an
	application server written in 100% Pure &java;.</para>

      <para>Tomcat is used for many purposes, and is not limited to
	Application Servers.  It provides an open platform to develop
	extensible web and content management services.  When Tomcat is
	used with an optimized FreeBSD system, it can provide highly
	reliable and fast pacing services.</para>

      <para>Please refer to the <xref linkend="ref"> section for more
	information on Tomcat and <acronym>&jsp;</acronym>.  The next
	section will demonstrate how to build the <quote>Tomcat
	Environment</quote> for FreeBSD.  The version of Tomcat used in
	this guide is <literal>4.0.6</literal>.  This version contains
	major bug fixes, and the following updates/changes:</para>

      <itemizedlist>
	<listitem>
	  <para><literal>JSP 1.2 Specification</literal></para>
	</listitem>

	<listitem>
	  <para><literal>Java Servlet 2.3 Specification</literal></para>
	</listitem>

	<listitem>
	  <para><literal>Full backward compatibility with the Java Servlet
	    2.2 and JSP 1.1 Specification</literal></para>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2>
      <title>The Tomcat environment for FreeBSD</title>

      <para>It is very simple to install Tomcat on a FreeBSD machine,
	after setting up the necessary &java; environment, which we have
	previously completed.</para>

      <para>In-order to set up Tomcat on FreeBSD, follow the below 
        procedure:</para>

      <procedure>
	<step>
	  <para>Follow the above steps to set up the necessary &java;
	    environment.</para>
	</step>

	<step>
	  <para>Set an environment variable <envar>JAVA_HOME</envar>
	    which, points to the directory where you have installed the
	    &jdk; (the examples below point to a native build of the
	    &jdk;).  If you are using &man.sh.1; as your shell, you can set
	    <envar>JAVA_HOME</envar> with:</para>

	  <screen>&prompt.root; export JAVA_HOME="/usr/local/jdk1.3.1"</screen>

	  <para>Those who use &man.csh.1; or a compatible shell, must use a
	    slightly different command:</para>

	  <screen>&prompt.root; setenv JAVA_HOME /usr/local/jdk1.3.1</screen>

	  <para>This environment variable should be made permanent by
	    adding it into either <filename>.profile</filename> or
	    <filename>.cshrc</filename>, depending on the shell you are
	    using. This variable is very crucial for the functioning of
	    all the &java; based programs, including Tomcat itself.</para>
	</step>

	<step>
	  <para>Download the Tomcat <quote>binary distribution</quote>
	    from the Jakarta website, which is located at
	    <literal><ulink url="&tomcat406"></ulink></literal>.  The
	    file to download is called
	    <filename>jakarta-tomcat-4.0.6.tar.gz</filename>.</para>	    
	</step>

	<step>
	  <para>The compressed and archived file we downloaded in the
	    previous step uses special <quote>GNU Extensions</quote>.
	    In-order to untar and uncompress the file, we will need to
	    install <literal>GNU Tar  (<filename
	    role="package">archivers/gtar</filename>)</literal>, by
	    doing the following:</para>

	  <screen>&prompt.root; cd /usr/ports/archivers/gtar &amp;&amp; make all install clean</screen>
	</step>

	<step>
	  <para>Un-tar and Un-compress the
	    <filename>jakarta-tomcat-4.0.6.tar.gz</filename> file into
	    the <filename>/usr/local</filename> directory and rename the
	    directory to <filename>tomcat-4.0</filename> for ease of
	    reference:</para>

	  <screen>&prompt.root; cd /usr/local
&prompt.root; gtar zxvf jakarta-tomcat-4.0.6.tar.gz
&prompt.root; ls jakarta*
jakarta-tomcat-4.0.6
&prompt.root; mv jakarta-tomcat-4.0.6 tomcat-4.0</screen>

	  <para>You can remove the
	    <filename>jakarta-tomcat-4.0.6.tar.gz</filename> at your
	    preference.</para>
	</step>
      </procedure>

      <note>
	<para><literal>Installation by using the source code is currently
	  out of scope for this document.  Please refer to the following
	  files for addition information on building from source,
	  available from your Tomcat distribution
	  directory:</literal></para>

	<itemizedlist>
	  <listitem>
	    <para><filename>/usr/local/tomcat-4.0/README.txt</filename></para>
	  </listitem>

	  <listitem>
	    <para><filename>/usr/local/tomcat-4.0/BUILDING.txt</filename></para>
	  </listitem>
	</itemizedlist>
      </note>
    </sect2>

    <sect2>
      <title>Operating Tomcat - Basics</title>

      <para>Now that we have finished installing Tomcat.  The following
	example shows how to start the Tomcat server:</para>

      <screen>&prompt.root; cd /usr/local/tomcat-4.0/bin
&prompt.root; ./startup.sh  (for starting Tomcat)</screen>

      <para>You can test if your Tomcat server has started by visiting
	the following URL: <literal>http://127.0.0.1:8080</literal> or
	<literal>http://localhost:8080</literal>.  To stop
	Tomcat:</para>

      <screen>&prompt.root; cd /usr/local/tomcat-4.0/bin
&prompt.root; ./shutdown.sh</screen>

      <para>(for stopping Tomcat)</para>

      <para>The <filename>startup.sh</filename> and
	<filename>shutdown.sh</filename> are frontends to the
	<filename>catalina.sh</filename> executable script in the same
	directory; if you would like to start Tomcat automatically at
	boot-time run:</para>

      <screen>&prompt.root; cd /usr/local/etc/rc.d
&prompt.root; ln -s /usr/local/tomcat-4.0/bin/catalina.sh</screen>

      <para>Edit the <filename>catalina.sh</filename>, and add the
	following at the beginning of the file (after the comment
	box):</para>

      <programlisting>JAVA_HOME=/usr/local/jdk1.3.1</programlisting>

      <para>If your port <literal>8080</literal> is occupied by some other
	service, you can change it by editing the
	<filename>server.xml</filename> in your Tomcat's
	<filename>conf/</filename> directory.  In the example below, the
	port will be changed to 80, assuming there is no service running
	on that port.</para>

      <screen>&prompt.root; cd /usr/local/tomcat-4.0/conf
&prompt.root; fgrep -n 8080 server.xml
~65:         By default, a non-SSL HTTP/1.1 Connector is established on port 8080.
~89:         port="8080" minProcessors="5" maxProcessors="75"
&prompt.root; cat server.xml | sed s/8080/80/ > server.xml.new
&prompt.root; mv server.xml.new server.xml</screen>
    </sect2>
  </sect1>

  <sect1 id="ref" xreflabel="reference">
    <title>Reference</title>

    <informaltable frame="none">
      <tgroup cols="1">
	<tbody>
	  <row>
	    <entry>
	      <ulink url="&wwwurl;/java">The FreeBSD &java; Project</ulink>
	    </entry>
	  </row>

	  <row>
	    <entry>
	      <ulink url="http://java.sun.com">JavaSoft. Home of &java;</ulink>
	    </entry>
	  </row>

	  <row>
	    <entry>
	      <ulink
		url="&sunurl;/software/communitysource/java2/licensing.html">The
		Sun Community Source Licensing for &java;</ulink>
	    </entry>
	  </row>

	  <row>
	    <entry>
	      <ulink url="&tomcaturl">Jakarta Tomcat Homepage</ulink>
	    </entry>
	  </row>

	  <row>
	    <entry>
	      <ulink url="http://java.sun.com/docs/index.html">J2SE
		Documentation</ulink>
	    </entry>
	  </row>

	  <row>
	    <entry>
	      <ulink url="&wwwurl;/ports/java.html">FreeBSD Ports - &java;
		Section</ulink>
	    </entry>
	  </row>
	</tbody>
      </tgroup>
    </informaltable>

    <sect2>
      <title>Conclusion</title>

      <para>Finally, we are at the end of the article and have a working
	version of Tomcat.  We hope that you have learned the basics of
	installing and building the &java; Development Kit on FreeBSD,
	along with installation of the Tomcat binary distribution
	application server released by the Apache Software Foundation.
	The <xref linkend="ref"> section contains pointers to additional
	resources on this topic, some which are in print, some which are
	on the World Wide Web, or both.</para>

      <para>The most important thing is drive space.  I suggest having
	<literal>700MB</literal> or more free space in
	<filename>/usr</filename>.  I hope this article has helped you
	in some small way.  For questions, comments, compliments, or
	rants, please direct them to the authors.</para>
    </sect2>
  </sect1>
</article>