<chapter id="ch-deploying-to-live">
    <title>Building and Deploying A Package</title>

    <para>
      To install your customized code to the production server you
will need to package the codebase with <firstterm>RPM</firstterm>.
RPM is available for most flavours of UNIX, including
    &RHEL; and <trademark>Solaris</trademark>. This section outlines
the steps for building a new RPM and installing it on your production
or staging server.
    </para>

    <sect1 id="s1-building-package">
        <title>Building a package</title>

        <para>Deployment to a live server is done by creating a package from a
        tested and known good instance and installing it on your live
        servers.</para>

        <sect2 id="s2-setting-up-instance">
            <title>Setting up an Instance</title>

            <para>An RPM is built from a staging or development instance. You
            will have a dev directory setup which contains all the code you
            intend to run on your live server. The first step is to ensure the
            quality of the instance you are building from.</para>

            <para>First you should do a clean and rebuild of your instance. With
            your environment setup for appropriate instance using
            <command>ccm-profile</command>, execute the following commands from
            the top level dev directory:</para>

<screen>
<command>ccm-stop</command>
<command>ant</command> <option>clean</option>
<command>ant</command> <option>deploy</option>
<command>ccm-start</command>
</screen>
            
            <para>Once this has completed you should test it extensively, but
            concentrating specifically on anything you may have changed since
            the last build. When you are happy with it, you can create a
            package.</para>
        </sect2>

        <sect2 id="s2-creating-a-package">
            <title>Creating a package</title>

            <para>Before creating a package, you should first increment the
            version or release number as described in <xref
            linkend="s2-application-dot-xml">. Be sure to commit your change to CVS
            if you are using it.</para>

            <para>Creating a package only requires a single command. In the top
            level dev directory there will be a file called
            <filename>rollingbuild.sh</filename>. To execute it, type:</para>

<screen>
<command>./rollingbuild.sh</command>
</screen>

            <para><command>rollingbuild.sh</command> does a complete build from
            scratch and can potentially take a long time to run. By default it
            also builds more than one type of package. To make it run quicker,
            you can use the following command instead:</para>

<screen>
<command>CCM_DIST_NOZIPS=1 ./rollingbuild.sh</command>
</screen>

        </sect2>

        <sect2>
          <title>RPM version</title>
          <para>
            You will want to increment the release and version numbers of your
            packages everytime you create a new build. You can do this
by editing <filename>project.xml</filename> or
          <filename>application.xml</filename>. Please see <xref linkend="s2-ax-release"/>. 
          </para>
          <caution>
            <para>
              If you do not increment the release number you will not
be able to upgrade an existing installation without using the
              <command>rpm --force</command> option. You should
<emphasis>always</emphasis> increment the release number no matter how
insignificant the change is. Having good accounting in terms of
releases allows you to revert to older versions.
            </para>
          </caution>
        </sect2>

        <sect2 id="s2-file-locations">
            <title>File locations</title>

            <para><command>rollingbuild.sh</command> creates a number of rpms
            which are arranged according to convention. All of the rpms are
            created in the directory
            <filename>/var/ccm-devel/rpm/<replaceable>username</replaceable>/RPMS/noarch</filename>. The source RPM is in <filename>/var/ccm-devel/rpm/<replaceable>username</replaceable>/SRPMS/</filename></para>

            <para>When it finishes, rollingbuild will have created a number of
            packages. 
            <itemizedlist>
              <listitem><para>
                <filename><replaceable>projectname</replaceable>-x.x.x-x.noarch.rpm</filename> - This is the binary RPM of the code base.
              </para></listitem>
              <listitem><para>
                <filename><replaceable>projectname</replaceable>-servlet-resin-x.x.x-x.noarch.rpm</filename> - This is the RPM for running your project with the Resin servlet container.
              </para></listitem>
              <listitem><para>
                <filename><replaceable>projectname</replaceable>-servlet-tomcat3-x.x.x-x.noarch.rpm</filename> - This is the RPM for running your project with the Tomcat servlet container.
              </para></listitem>
              <listitem><para>
              <filename><replaceable>projectname</replaceable>-devel-tomcat3-x.x.x-x.noarch.rpm</filename> - This is the RPM for creating another project that extends the current project. This will install code in <filename>/usr/share/ccm-devel/project</filename>.
              </para></listitem>
              <listitem><para>
<filename><replaceable>projectname</replaceable>-doc-x.x.x-x.noarch.rpm</filename> - This is the javadoc generated from your project code. It will include all the APLAWS and &CCM; Javadoc.
              </para></listitem>
              <listitem><para>
<filename><replaceable>projectname</replaceable>-x.x.x-x.src.noarch.rpm</filename> - This is the source RPM for your project.
              </para></listitem>
            </itemizedlist>
          </para>
          </sect2>
        </sect1>
          <sect1 id="s1-install-project">
            <title>Installing your RPM</title>
            <para>
              Once you have created your RPM you will need to install
it on your staging or production machine. Here are the steps for
              installing your RPMS, you will need to be logged in as the root user.</para>

              <sect2 id="s2-install-quick">
                <title>Quick steps for the impatient</title>
              <orderedlist>
                <listitem><para>Copy two RPMs,
                <filename><replaceable>projectname</replaceable>-x.x.x-x.noarch.rpm</filename>,
and
                <filename><replaceable>projectname</replaceable>-servlet-resin-x.x.x-x.noarch.rpm</filename>
to your staging server.
              </para></listitem>
              <listitem><para>
                Install the two RPMs at once by running the following command.
<screen>
  <command>rpm -Uvh <replaceable>projectname-x.x.x-x.noarch.rpm projectname</replaceable>-servlet-resin-x.x.x-x.noarch.rpm</command>
</screen>
              </para></listitem>
              <listitem><para>
                Copy the file <filename>/etc/<replaceable>projectname</replaceable>.cfg-resin</filename> to <filename>/etc/<replaceable>projectname</replaceable>.cfg</filename>.
</para></listitem>
<listitem><para>
  Edit <filename>/etc/<replaceable>projectname</replaceable>.cfg</filename> in the same way you edited <filename>config.vars</filename>.
</para></listitem>
<listitem><para>
  Update the configuration files for your server by running <command><replaceable>projectname</replaceable>-configure.pl</command>. This is similar to running <command>ant make-init</command>.
<screen>
/usr/sbin/<replaceable>projectname</replaceable>-configure.pl /etc/<replaceable>projectname</replaceable>.cfg
</screen>
</para></listitem>
<listitem><para>
The server should restart automatically when the configuration files are changed. If this does not happen you can restart the server manually with the init script.
<screen>
/etc/init.d/<replaceable>projectname</replaceable> restart # stop|start
</screen>
</para></listitem>
</orderedlist>
</sect2>
          <sect2 id="s2-install-rpm-project">
            <title>Installing the RPMS: <filename><replaceable>projectname</replaceable>-x.x.x-x.noarch.rpm</filename></title>
            <para>
              You will need to install the two RPMs
<filename><replaceable>projectname</replaceable>-x.x.x-x.noarch.rpm</filename>,
and
<filename><replaceable>projectname</replaceable>-servlet-resin-x.x.x-x.noarch.rpm</filename>
together as the two are
interdependent. <filename><replaceable>projectname</replaceable>-x.x.x-x.noarch.rpm</filename>
will install your code in
<filename>/var/www/<replaceable>projectname</replaceable></filename>
where it will be used by your application server. This RPM also
installs the init file
<filename>/etc/init.d/<replaceable>projectname</replaceable></filename>,
the configuration script
<filename>/usr/sbin/<replaceable>projectname</replaceable>-configure.pl</filename>,
and the log directory
<filename>/var/log/<replaceable>projectname</replaceable>.</filename>
            </para>
          </sect2>
          <sect2 id="s2-install-rpm-servlet">
            <title>Installing the RPMS: <filename><replaceable>projectname</replaceable>-servlet-resin-x.x.x-x.noarch.rpm</filename></title>
            <para>
              The servlet RPM will install configuration files and
wrapper scripts for controlling the servlet container. Specifically it will install the following files:
              <itemizedlist>
                <listitem><para><filename>/usr/share/<replaceable>projectname</replaceable>/bin/resin/run-apache.sh.in</filename></para></listitem>
                <listitem><para><filename>/usr/share/<replaceable>projectname</replaceable>/bin/resin/run-resin.sh.in</filename></para></listitem>
                <listitem><para><filename>/usr/share/<replaceable>projectname</replaceable>/bin/resin/run.sh.in</filename></para></listitem>
                <listitem><para><filename>/usr/share/<replaceable>projectname</replaceable>/conf/resin</filename></para></listitem>
                <listitem><para><filename>/usr/share/<replaceable>projectname</replaceable>/conf/resin/httpd-resin-vhost.conf.in</filename></para></listitem>
                <listitem><para><filename>/usr/share/<replaceable>projectname</replaceable>/conf/resin/resin-back.conf.in</filename></para></listitem>
                <listitem><para><filename>/usr/share/<replaceable>projectname</replaceable>/conf/resin/resin-front.conf.in</filename></para></listitem>
</itemizedlist>
            </para>

            <para>
              These files are templates for your installation. When
you run the command
<command>/usr/sbin/<replaceable>projectname</replaceable>-configure.pl</command>
copies of these files will be placed in
<filename>/var/www/<replaceable>projectname</replaceable>/conf</filename>
and
<filename>/var/www/<replaceable>projectname</replaceable>/bin</filename>. They
will also be edited to reflect the parameters you set in
<filename>/etc/<replaceable>projectname</replaceable>.cfg</filename>
            </para>
          </sect2>

          <sect2 id="s2-project-dot-cfg">
            <title>The <filename><replaceable>projectname</replaceable>.cfg</filename></title>
            <para>
              Once the RPMs are installed you will need to edit the
configuration file for your server. The template for the config file
is
              <filename>/etc/<replaceable>projectname</replaceable>.cfg-resin</filename>. Copy
this file to
<filename>/etc/<replaceable>projectname</replaceable>.cfg</filename>
and edit the parameters much like how you edited
<filename>config.vars</filename>. Some of the parameters are not in
<filename>config.vars</filename> and you will need to change the
values depending on how your Resin and HTTP servers are set up. Below
is an example of a configuration file for a production installation
with two Resin application servers and one Apache front end. The
values you need to change in addition to what what you find in
<filename>config.vars</filename> is emphasised with additional
comments.  The Resin servers are called resin1.example.com and
resin2.example.com and the Apache server is called apache.example.com.
            </para>
         
            <note>
              <title><command>hostname</command></title>
              <para>The hostnames for the servers need to be exactly
as they appear when you run the <command>hostname</command>
command. If you want to change the default behavior of
<command>hostname</command> to return the short name or the fully
qualified domain name here is what you can do: 
</para>
<para>
  Edit <filename>/etc/sysconfig/network</filename> and change HOSTNAME
to be the fully qualified domain name. You can also use the gui tools
<command>netconfig</command> and
<command>redhat-config-network</command> to do this. These changes
will only take effect after the machine has been restarted. To change
it at runtime pass an argument to <command>hostname</command> as root.
<screen>
$ hostname resin1.example.com
</screen>

You can test this by running <command>hostname</command> with no
arguments.  </para>
            </note>

            <screen><computeroutput>
##########################################
# APLAWS Master configuration file #
#########################################

servlet-container = resin
## This is set to servlet23 by default but should be resin 
<userinput>servlet-webxml = resin</userinput> 

# NB: all hostnames used should be
# the fully qualified name as returned
# by the 'hostname' command with no arguments.

####################################
# UNIX system level configuration

# Installation directory for resin
## This should be the directory of your Resin installation
<userinput>resin-home = /opt/resin/2.1.8</userinput> 

# Installation directory for this app
app-home = /var/www/aplaws


# Directory containing the base runtime & config files
runtime-home = /usr/share/aplaws

# UNIX accounts to run as
user = servlet
group = servlet

# Whereever you installed JDK 1.3.1
# java-home = /usr/j2se
# java-home = /usr/java/jdk1.3.1
## The java-home should point to $JAVA_HOME
<userinput>java-home = /opt/IBMJava2-131</userinput>

# Userinputly tell java to use more memory
#
# For Sun's JDK, on a machine with 1GB
#jre-args = -J-client -J-Xss128k -J-Xms512m -J-Xmx512m -J-XX:NewSize=128m -J-XX:MaxNewSize=128m
#
# For IBM's JDK on a machine with 256MB
#jre-args = -J-Xms128m -J-Xmx128m
<userinput>jre-args = -J-Xms1536m -J-Xmx1536m</userinput>

# The hostname of the front end apache box
<userinput>apache = apache.example.com</userinput>

# The hostnames of the back end resin boxes
<userinput>resin = resin1.example.com</userinput>
<userinput>resin = resin2.example.com</userinput>

# The SRUN ports for apache to talk to the resin
# boxes. The 'hostname:port' pair designates which
# srun port each resin instance listens on.
# If there is a firewall, between the resin and
# apache boxes, a second 'hostname:port' pair
# specifies the host and port of the firewall
#
# eg1. no firewall
<userinput>srun = resin1.example.com:6802</userinput>
<userinput>srun = resin2.example.com:6802</userinput>

# eg2. with firewall
<userinput>#srun = resin1.example.com:6082, firewall:6802</userinput>
<userinput>#srun = resin2.example.com:6082, firewall:6803</userinput>

# Turn on http listening on either apache
# or resin boxes. Only need http port on
# the resin boxes for debugging purposes
<userinput>http = apache.example.com:80</userinput>

# Only for debugging
<userinput>http = resin1.example.com:8080</userinput>
<userinput>http = resin2.example.com:8080</userinput>

# ACS initialization file
admin-answer = 6
admin-email = admin@example.com
admin-forename = Administrator
admin-password = 123456
admin-question = 12345
admin-surname = Account
cache-expiry = 900
<userinput>cache-peers = "http://resin1.example.com:8080"</userinput>
caching-active = yes
db-pass = aplaws_xyz
db-pool = 150
db-user = aplaws
debug-mode = false
default-locale = en_US
default-scheme = http
developer-support = false
dispatcher-context-path = 
dispatcher-servlet-path = 
dmi-active = false
dmi-data-model-file = "/WEB-INF/sql/ccm-core/default/dmi/dmi-create.sql"
dmi-xml-files = { "core-dmi.xml", "/WEB-INF/sql/ccm-core" }
<userinput>host-name = apache.example.com</userinput>
<userinput>hostname = apache.example.com</userinput>
jdbc-url = jdbc:postgresql://postgres.example.com/aplaws
log-dir = /var/log/aplaws
log-level = warn
log-size = 1000000
login-stylesheet = login_en.xsl
lucene-index-location = /var/www/aplaws/lib/lucene-index
permissionsDMLChecking = false
search-intermedia-enabled = false
search-lucene-enabled = true
search-lucene-indexer-id = 2
<userinput>server-name = apache.example.com</userinput>
server-port = 80
sitename = APLAWS
smtp-host = localhost
state-dir = /var/www/aplaws/lib
subsite-dispatcher-class = com.arsdigita.ui.login.SubsiteDispatcher
xslt-engine = Saxon
xslt-timeout = 60000

# WCT CMS Initialization File
content-digest-sender = article-digest@example.com
forms-content-digest-sender = forms-digest@foo.com
inso_filter_works = 0
<userinput>publish-to-fs-servers = "http://resin1.example.com/", "http://resin2.example.com/"</userinput>
<userinput>publish-to-fs-source = "http://resin2.example.com/"</userinput>
<userinput>publish-to-fs-this-server = "http://resin2.example.com/"</userinput>
search-engine = lucene

# Version: $Id: building-packages.sgml 287 2005-02-22 00:29:02Z sskracic $ $Date: 2004/07/29 $
adminCanEditPosts = true
authorCanEditPosts = true
digestUserEmail = digests
<userinput>replyHostName = apache.example.com</userinput>

# Navigation initialization file
default-content-section-url = "/content/"

# System Properties
project-name = aplaws
</computeroutput>
</screen>
</sect2>

<sect2 id="s2-aplaws-configure-dot-pl">

  <title><command>/usr/sbin/<replaceable>projectname</replaceable>-configure.pl</command></title>

  <para>
    Once you have edited
<filename>/etc/<replaceable>projectname</replaceable>.cfg-resin</filename>
you can run
<command>/usr/sbin/<replaceable>projectname</replaceable>-configure.pl</command>
to generate the config files and the run scripts for your server to
use.  Make sure that you do not get errors after you run this
command. <command>/usr/sbin/<replaceable>projectname</replaceable>-configure.pl</command>
copies files from
<filename>/usr/share/<replaceable>projectname</replaceable>/bin/resin/</filename>
and replaces the parameter values with what you have set in the
configuration file and places them in
<filename>/var/www/<replaceable>projectname</replaceable>/conf</filename>. It
also generates the wrapper run scripts in
<filename>/var/www/<replaceable>projectname</replaceable>/bin</filename>.
 </para> 
</sect2>

<sect2 id="s2-etc-init-dot-d">
  <title><command>/etc/init.d/<replaceable>projectname</replaceable></command></title>
  <para>
    Once the configuration files and the wrapper scripts are written
you can start, stop, and restart your sever using
    <command>/etc/init.d/<replaceable>projectname</replaceable></command>.
The log files are located in your specified directory, by default
<filename>/var/log/<replaceable>projectname</replaceable></filename>. You
should <command>tail -f
/var/log/<replaceable>projectname</replaceable>/*.log</command> to
monitor the progress of your server startup.
  </para>
  <note>
    <title><command>/etc/init.d/<replaceable>projectname</replaceable></command> restart </title>
    <para>
      When you restart the server the command will pause for a number
of seconds to wait for the application server to completely exit. 
    </para>
  </note>
</sect2>
    </sect1>
</chapter>




















