head	1.3;
access;
symbols;
locks; strict;
comment	@# @;


1.3
date	2001.08.08.19.56.52;	author edk;	state Exp;
branches;
next	1.2;

1.2
date	2001.08.08.18.46.55;	author edk;	state Exp;
branches;
next	1.1;

1.1
date	2001.08.08.17.49.26;	author edk;	state Exp;
branches;
next	;


desc
@@


1.3
log
@correct product name
@
text
@<html><head><title>Building a sandbox</title></head>
<body>
<h2>Overview</h2>

This document contains a technical outline of the operations involved in
building a sandbox.  First, a bit about per-instance configuration:

<p>
The per-instance configuration is split into two locations -- the instance
module and env.sh.  The instance module will be covered elsewhere; env.sh
has quite a few tokens, which won't be covered in depth.  Before building a
sandbox, env.sh must generally be sourced.

<p>Generally as much of the per-instance configuration should be done before
building the sandbox as possible.

<h3>checking out a sandbox</h3>

On a machine which is already set up with the appropriate RPMs, it may be
possible to use a script called sandbox_checkout.bash.  This script is
maintained in releng/scripts; it takes the following arguments:
<table>
<tr><td>-t</td><td>tag to use for tigris</td></tr>
<tr><td>-i</td><td>instance (possibly tigrisinst)</td></tr>
<tr><td>-r</td><td>instance tag</td></tr>
<tr><td>-u</td><td>user as whom to do the cvs checkout</td></tr>
<tr><td>-d</td><td>dir into which to place things (default 'sandbox')</td></tr>
</table>

Generally the first three will be most useful; the -u option will be useful
iff your unix user account is not the same as your tigris account on
tigris.org.

<p>If you are setting up a production sandbox, you may wish to download a
tagged tarball from releng.tigris.org, in the downloads section.  If you're
setting up a developer sandbox and don't want to use sandbox_checkout.bash,
something like the following may suffice:

<pre>
        cd ~
        cvs -d :pserver:$USER@@cvs.tigris.org:/cvs login
        cvs -d :pserver:$USER@@cvs.tigris.org:/cvs co sandbox
        cd sandbox
        cvs -d :pserver:$USER@@cvs.tigris.org:/cvs co anzu helm eyebrowse \
                issuezilla tigrisinst
</pre>

The exact list on the last line will depend on the version of tigris which
you're using; before 1.2 will require joist (and issuezilla should not be
listed); and after 1.2 will not require joist (but will require issuezilla).

<h3>Building instructions</h3>

<p>Note that generally the blessed ways to create an initial sandbox -- once
you have one ready in the filesystem -- are as follows:

<pre>
        cd $SANDBOX
        source scripts/env.sh
        cd helm/scripts
        ./install.sh
</pre>

and:

<pre>
        cd $SANDBOX
        source scripts/env.sh
        cd helm/scripts
        ./dev_install.sh
</pre>

The former is for port 80 sandboxes, and the latter is for developer
sandboxes.  These operations will tend to delete data, and should only be used
during initial install.

<p>The only generally blessed way to update a sandbox after updating code via
cvs or making changes is through the top level sandbox make file.  In many
situations, short cuts are possible; but if things don't work as expected, the
thing to do is as follows:

<pre>
        cd $SANDBOX
        source scripts/env.sh
        make
</pre>

If you've updated from one version of tigris to another, you may need to
do something like the following:

<pre>
        cd $SANDBOX
        source scripts/env.sh
        cd helm/scripts
        ./update_tigris $old_tag $new_tag
</pre>

Note that this will not seed the sandbox with initial data.

<h3>Component make files / ant build files</h3>
Each sandbox component (and the semi-components search, issuezilla, and
cvsweb) must support a simple syntax for building:
<pre>
        cd $SANDBOX/$component
        make
        make install
</pre>

However, there are a few special relationships which are known about in the
sandbox make file (discussed below).

<h3>Component configuration</h3>
Each component may optionally define a set of configuration parameters to be
used when manipulating the files contained in that component.  At present,
this system is largely unused due to the desire to restrict the number of
files which are edited to provide per-instance configuration.  These are
defined in $SANDBOX/$component/conf/configure.properties, in a simple
name-value format.

<h3>configure.pl</h3>
configure.pl is a perl script which looks for files whose name ends in .in.
It operates based on the env.sh, env_check, and the per-component
configuration files.  It is used to replace tokens (such as __DOMAIN__) in the
.in files with the value appropriate for this sandbox / instance.  A few of
the tokens are generated based on other values (HTTP_PORT, JSERV_PORT, and
SSL_PORT in particular).

<p>
For each file which configure.pl finds, it opens the file for reading, opens
the file (minus the .in suffix) for writing, and processes the file line by
line.  For each thing it finds which looks like __{NAME}__ it checks to see if
{NAME} is a token it knows about.  If so, that entire string is replaced by
the value of the token; otherwise, configure.pl complains and leaves the
string untouched.  Once configure.pl is finished processing the file, it
chmods it to have the same modes as the original .in file.

<p>
By default, configure.pl will go through the entire sandbox (including the
data directory).  This is fine during install, but can cause problems latter
(if for no other reason, then simply because going through the data directory
may take prohibitively long).  So there is a way to tell configure to operate
on only a single directory (and its subdirs).  For that, provide the name of
the directory as the first and only argument to configure.pl

<h3>reconfigure.pl</h3>
reconfigure.pl is a perl script which transforms fragments of a conf file into
the complete conf file -- respecting order.  It has a hardcoded list of conf
files which it will process; technically, it might well be useful for problems
other than conf files as well, but that's the only current use we have.

<p>
For each of the conf file in the hardcoded list, eg. file=servlets,
reconfigure.pl looks for $SANDBOX/conf/$file.d.  It reads the lists of files
in that directory and generates a list of the files which end in .servlets,
and whose names begin with two digits.  It sorts these files based on the
leading two digits; it then combines them (in sorted order) into
$SANDBOX/conf/$file.

<h3>sandbox level make</h3>
This make file is responsible for installing the application.  It knows about
using configure.pl, reconfigure.pl, patch_permissions, and the individual
components which are part of the sandbox.  It knows about some dependencies,
in terms of building certain components before building others.

<h3>dev_install.sh</h3>
This script knows about calling the top level make file.  It also knows how to
seed the data directory and the database with initial data for mail, cvs,
helm, and so on.

<h3>install.sh</h3>
This script knows about everything which dev_install.sh knows about; in
addition to those operations, it attempts to create the users and will
generally be able to set up the crontab for a port 80 sandbox.

</body></html>
@


1.2
log
@add information about how to checkout / get a sandbox
@
text
@d88 1
a88 1
If you've updated from one version of sourcecast to another, you may need to
@


1.1
log
@instructions and some technical details regarding building sandboxes
@
text
@d17 35
d54 2
a55 2
<p>Note that generally the blessed ways to create an initial sandbox are as
follows:
@

