469 lines
19 KiB
Plaintext
469 lines
19 KiB
Plaintext
<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>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|