<?xml version='1.0' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
               "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % myvars SYSTEM "../variables.ent">
%myvars;
]>
<sect1 id="bootstrap-acs" xreflabel="Bootstrapping OpenACS">
<title>Bootstrapping OpenACS</title>

<authorblurb>
<para>By <ulink url="mailto:jsalz@mit.edu">Jon Salz</ulink> </para>
</authorblurb>

<itemizedlist>
<listitem><para>Tcl code: /tcl/0-acs-init.tcl and /packages/acs-kernel/bootstrap.tcl</para></listitem>
</itemizedlist>

<para>This document describes the startup (bootstrapping) process for an AOLserver
running OpenACS. 
</para>


<sect2 id="bootstrap-acs-bigpicture">
<title>The Big Picture</title>

<para>
Before OpenACS 3.3, the OpenACS startup process was extremely simple: after AOLserver
performed its internal initialization (reading the configuration file,
loading shared libraries and module code, etc.) it scanned through the Tcl
library directory (generally <computeroutput>/var/lib/aolserver/</computeroutput><emphasis><computeroutput>yourservername</computeroutput></emphasis><computeroutput>/tcl</computeroutput>),
sourcing each file in sequence. 
</para>

<para>While this overall structure for initialization is still intact, package
management has thrown a wrench into the works - there are a few extra things
to do during initialization, most notably:</para>

<itemizedlist>
<listitem><para>Examine the OpenACS file tree for files that should not be present in OpenACS
(i.e., that were once part of the OpenACS distribution but have since been
removed).</para></listitem>

<listitem><para>Scan the <computeroutput>/packages</computeroutput> directory for new packages.</para></listitem>

<listitem><para>Initialize enabled packages by sourcing their <computeroutput>*-procs.tcl</computeroutput>
and <computeroutput>*-init.tcl</computeroutput> files.</para></listitem>
</itemizedlist>

<para>
This document examines in detail each of the steps involved in AOLserver/OpenACS
startup. 
</para>

</sect2>

<sect2 id="bootstrap-acs-startup-process">
<title>The Startup Process</title>

<para>
As soon as the <computeroutput>nsd</computeroutput> daemon is executed by the <computeroutput>init</computeroutput>
process (or otherwise), AOLserver reads its configuration file and
<computeroutput>chroot</computeroutput>s itself if necessary. It then loads shared libraries
indicated in the <computeroutput>.ini</computeroutput> file (e.g., the Oracle driver and
<computeroutput>nssock</computeroutput>), and sources Tcl module files (generally in
<computeroutput>/home/aol30/modules/tcl</computeroutput>). This step is, and has always been, the
same for all AOLservers, regardless of whether they are running OpenACS. 
</para>

<para>Next AOLserver sources, in lexicographical order, each file in the
<computeroutput>/tcl</computeroutput> directory. The first such file is
<computeroutput>0-acs-init.tcl</computeroutput>, which doesn&#39;t do much directly except to
determine the OpenACS path root (e.g., <computeroutput>/var/lib/aolserver/</computeroutput><emphasis><computeroutput>yourservername</computeroutput></emphasis>)
by trimming the final component from the path to the Tcl library directory
(<computeroutput>/var/lib/aolserver/</computeroutput><emphasis><computeroutput>yourservername</computeroutput></emphasis><computeroutput>/tcl</computeroutput>). But
<computeroutput>0-acs-init.tcl</computeroutput>&#39;s has an important function, namely sourcing
<computeroutput>/packages/acs-core/bootstrap.tcl</computeroutput>, which does the following:</para>

<orderedlist>
<listitem><para><emphasis role="strong">Initialize some NSVs used by the core</emphasis>. These NSVs are
documented in <computeroutput>/packages/acs-core/apm-procs.tcl</computeroutput> - no need to
worry about them unless you&#39;re an OpenACS core hacker. 

</para></listitem>

<listitem><para><emphasis role="strong">Verify the deletion of obsolete OpenACS files</emphasis>. The
<computeroutput>/tcl</computeroutput> directory has evolved quite a bit over the months and
years, and a few files have come and gone. The
<computeroutput>/www/doc/removed-files.txt</computeroutput> file contains a list of files which
<emphasis>must be deleted</emphasis> from the AOLserver installation, at the risk of
causing weird conflicts, e.g., having several security filters registered.
<computeroutput>bootstrap.tcl</computeroutput> scans through this list, logging error messages to
the log if any of these files exist. 

</para></listitem>

<listitem><para><emphasis role="strong">Source <computeroutput>*-procs.tcl</computeroutput> files in the OpenACS core</emphasis>.
We source each file matching the <computeroutput>*-procs.tcl</computeroutput> glob in the
<computeroutput>/packages/acs-kernel</computeroutput> directory, in lexicographical order. These
procedure are needed to perform any of the following steps. 

</para></listitem>

<listitem><para><emphasis role="strong">Ensure that the database is available</emphasis> by grabbing and
releasing a handle. If we can&#39;t obtain a handle, we terminate
initialization (since OpenACS couldn&#39;t possibly start up the server without
access to the database). 

</para></listitem>

<listitem><para><emphasis role="strong">Register any new packages in the <computeroutput>/packages</computeroutput>
directory</emphasis>. In each directory inside <computeroutput>/packages</computeroutput>, we look
for a <computeroutput>.info</computeroutput> file; if we find a package that hasn&#39;t yet been
registered with the package manager (i.e., it&#39;s been copied there
manually), we insert information about it into the database. (The first time
OpenACS starts up, <emphasis>no</emphasis> packages will have been registered in the database
yet, so this step will registers every single package in the
<computeroutput>/packages</computeroutput> directory.) Note that packages discovered here are
initially disabled; they must be manually enabled in the package manager
before they can be used. 

</para></listitem>

<listitem><para><emphasis role="strong">Ensure that the <computeroutput>acs-kernel</computeroutput> package is
enabled</emphasis>. If the OpenACS core isn&#39;t initialized, the server
couldn&#39;t possibly be operational, so if there&#39;s no enabled version of
the OpenACS core we simply mark the latest installed one as enabled. 

</para></listitem>

<listitem><para><emphasis role="strong">Load <computeroutput>*-procs.tcl</computeroutput> files for enabled
packages</emphasis>, activating their APIs. 

</para></listitem>

<listitem><para><emphasis role="strong">Load <computeroutput>*-init.tcl</computeroutput> files for enabled packages</emphasis>,
giving packages a chance to register filters and procedures, initialize data
structures, etc. 

</para></listitem>

<listitem><para><emphasis role="strong">Verify that the core has been properly initialized</emphasis> by
checking for the existence of an NSV created by the request processor
initialization code. If it&#39;s not present, the server won&#39;t be
operational, so we log an error.</para></listitem>
</orderedlist>

<para>
At this point, <computeroutput>bootstrap.tcl</computeroutput> is done executing. AOLserver
proceeds to source the remaining files in the <computeroutput>/tcl</computeroutput> directory
(i.e., unpackaged libraries) and begins listening for connections. 
</para>



<para><phrase role="cvstag">($Id: bootstrap-acs.xml,v 1.7 2006/07/17 05:38:38 torbenb Exp $)</phrase></para>
</sect2>
</sect1>
