bootstrap-acs.xml
Delivered as text/xml
[ hide source ] | [ make this the default ]
File Contents
<?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-bootstrap-installer/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>
When <computeroutput>nsd</computeroutput> is started, it reads its configuration file and
<computeroutput>chroot</computeroutput>s itself if necessary. It then
loads the configured modules (e.g., Database and network drivers, Tcl module files).
This step is, and has always been, the
same for all NaviServer/AOLservers, regardless of whether they are
running OpenACS (see the NaviServer/AOLserver documentation for more details).
</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'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>'s has an important function, namely sourcing
<computeroutput>/packages/acs-bootstrap-installer/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're an OpenACS core hacker.
</para></listitem>
<listitem><para><emphasis role="strong">Verify that OpenACS is fully
installed</emphasis>. If not (e.g. at the first installation) it
prompts a form for providing essential information about the installation.
</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't obtain a handle, we terminate
initialization (since OpenACS couldn'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't yet been
registered with the package manager (i.e., it'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't initialized, the server
couldn't possibly be operational, so if there'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's not present, the server won'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.16.1 2019/03/02 19:30:06 gustafn Exp $)</phrase></para>
</sect2>
</sect1>
