<?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="install-steps">
  <title>Basic Steps</title>

  <para>
    The basic steps for installing OpenACS are:
  </para>

  <orderedlist>
    <listitem><para>Install an OS and supporting software (see <xref linkend="unix-installation"/> or <xref linkend="install-redhat"/> for more details).  See the <xref linkend="compatibility-matrix"/>.</para>
    </listitem>

    <listitem><para>Install a database (see <xref linkend="oracle"/> or
        <xref linkend="postgres"/>).</para>
    </listitem>

    <listitem>
      <para> Install AOLserver (<xref linkend="aolserver4"/>) .</para>
    </listitem>

    <listitem><para>Create a unique database and system user.
        Install the OpenACS tarball, start and AOLserver instance, and
        use the OpenACS web pages to complete installation
        (see <xref linkend="openacs"/>).</para>
    </listitem>
  </orderedlist>

  <para> Specific instructions are available for Mac OS X and
    Windows2000 (see <xref linkend="mac-installation"/> or
    <xref linkend="win2k-installation"/>).</para>

  <sect2 id="install-rpms">
    <title>Binaries and other shortcuts</title>

    <para>You can try out OpenACS using some binary installers. In
    general, they are not yet supported by the community, so they are
    mostly for evaluation purposes. <ulink url="http://openacs.org/faq/one-faq?faq_id=130897#130917">Installing
    OpenACS</ulink></para>

    <para>You can see a list of <ulink url="http://openacs.org/projects/openacs/installer">current installers</ulink>.
    </para>

    <orderedlist>
      <listitem>
        <para>
          The packaged version of
          PostgreSQL in Debian, Red Hat, and FreeBSD ports works fine.</para>
      </listitem>
      <listitem>
        <para>Once AOLserver and a database are installed, a bash script <link
            linkend="install-with-script">automates the OpenACS checkout and
            installation</link>.
        </para>
      </listitem>
    </orderedlist>
  </sect2>


  <sect2 id="install-requirements">
    <title>System Requirements</title>
    <para>
      You will need a PC (or equivalent) with at least these minimum
      specifications:
    </para>
    <itemizedlist>
      <listitem><para>128MB RAM (much more if you want Oracle)</para></listitem> 
      <listitem><para>1GB free space on your hard drive (much more if you want Oracle)</para></listitem>
      <listitem><para>A Unix-like operating system with Tcl, tDOM, and
          a mail transport agent like sendmail or qmail. (see <xref
            linkend="individual-programs"/>)</para>
      </listitem>
    </itemizedlist><para>
      All of the software mentioned is open-source and available without direct costs,
      except for Oracle. You can obtain a free copy of Oracle for
      development purposes. This is described in the <xref
        linkend="install-oracle-getit"/> section.
    </para>

  </sect2>

  <sect2 id="how-to-use">
    <title>How to use this guide</title>

    <itemizedlist>
      <listitem>
        <para><computeroutput>This</computeroutput> is text you will see on
          screen, such as a <computeroutput><guibutton><accel>B</accel>utton</guibutton></computeroutput> or <computeroutput><guilabel><accel>link</accel></guilabel></computeroutput>
          in a radio button list or menu.</para>
      </listitem>
      <listitem><para><userinput>This is text that you will type.</userinput></para></listitem>
      <listitem>
        <para>This is text from a program or file which you may need to
          examine or edit:</para>
        <programlisting>if {$database == "oracle"} {
          set db_password        "mysitepassword"
}</programlisting>
      </listitem>
      <listitem>
        <para>This is text that you will
          <computeroutput>see</computeroutput> and <userinput>type</userinput> in a command shell, including <replaceable>text you may have to
            change</replaceable>.  It is followed by a list of just the commands,
          which you can copy and paste. The command prompt varies by system; in the examples we use the form<computeroutput>[$OPENACS_SERVICE_NAME aolserver]$</computeroutput>, where <computeroutput>$OPENACS_SERVICE_NAME</computeroutput> is the current user and <computeroutput>aolserver</computeroutput> is the current directory.  The root prompt is shown ending in # and all other prompts in $.</para>
        <screen>
[root root]# <userinput>su - $OPENACS_SERVICE_NAME</userinput>
[$OPENACS_SERVICE_NAME aolserver]$ <userinput>svc -d /service/<replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput>
[$OPENACS_SERVICE_NAME aolserver]$ <userinput>dropdb <replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput>
DROP DATABASE
[$OPENACS_SERVICE_NAME aolserver]$ <userinput>createdb <replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput>
CREATE DATABASE
<action>su - $OPENACS_SERVICE_NAME
svc -d /service/<replaceable>$OPENACS_SERVICE_NAME</replaceable>
dropdb <replaceable>$OPENACS_SERVICE_NAME</replaceable>
createdb <replaceable>$OPENACS_SERVICE_NAME</replaceable></action></screen>
        <formalpara id="cut-and-paste-name-var">
          <title>Setting a global shell variable for cut and paste</title>
          <para>In order to cut and paste the instructions into your shell, you must set the environment variable $OPENACS_SERVICE_NAME.  In order to set it globally so that it works for any new users or special service users you may create, edit the file <computeroutput>/etc/profile</computeroutput> ( <computeroutput>/etc/share/skel/dot.profile</computeroutput> for FreeBSD) and add this line:</para>
        </formalpara>
        <programlisting>export OPENACS_SERVICE_NAME=<replaceable>service0</replaceable></programlisting>
      </listitem>
    </itemizedlist>
  </sect2>


  <sect2>
    <title>Paths and Users</title>
    
   <table pgwide="1">
      <title>Default directories for a standard install</title>
        <tgroup cols="2">
          <tbody>
            <row>
              <entry>Fully qualified domain name of your server</entry>
              <entry><replaceable>yourserver.test</replaceable></entry>
            </row>
            <row>
              <entry>name of administrative access account</entry>
              <entry>remadmin</entry>
            </row>
            <row>
              <entry>OpenACS service</entry>
              <entry><indexterm>
                  <primary>$OPENACS_SERVICE_NAME</primary>
                </indexterm>
                <replaceable>$OPENACS_SERVICE_NAME</replaceable> (set to service0 in default install)</entry>
            </row>
            <row>
              <entry>OpenACS service account</entry>
              <entry><replaceable>$OPENACS_SERVICE_NAME</replaceable></entry>
            </row>
            <row>
              <entry>OpenACS database name</entry>
              <entry><replaceable>$OPENACS_SERVICE_NAME</replaceable></entry>
            </row>
            <row>
              <entry>Root of OpenACS service file tree (SERVERROOT)</entry>
              <entry><replaceable>/var/lib/aolserver/$OPENACS_SERVICE_NAME</replaceable></entry>
            </row>
            <row>
              <entry>Location of source code tarballs for new software</entry>
              <entry>/var/tmp</entry>
            </row>
            <row>
              <entry>The OpenACS tarball contains some files which
                are useful while setting up other software.  Those
                files are located at:</entry>
              <entry>/var/tmp/&tarballpath;/packages/acs-core-docs/www/files</entry>
            </row>
            <row>
              <entry>Database backup directory</entry>
              <entry><replaceable>/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup</replaceable></entry>
            </row>
            <row>
              <entry>Service config files</entry>
              <entry><replaceable>/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc</replaceable></entry>
            </row>
            <row>
              <entry>Service log files</entry>
              <entry><replaceable>/var/lib/aolserver/$OPENACS_SERVICE_NAME/log</replaceable></entry>
            </row>
            <row>
              <entry>Compile directory</entry>
              <entry>/usr/local/src</entry>
            </row>
            <row>
              <entry>PostgreSQL directory</entry>
              <entry>/usr/local/pgsql</entry>
            </row>
            <row>
              <entry>AOLserver directory</entry>
              <entry>/usr/local/aolserver</entry>
            </row>
          </tbody>
        </tgroup>
    </table>

    <para>
      None of these locations are set in stone - they're simply
      the values that we've chosen.  The values that you'll
      probably want to change, such as service name, are
      <replaceable>marked like this</replaceable>.  The other
      values we recommend you leave unchanged unless you have a
      reason to change them.</para>

    <note>
      <para>
        Some of the paths and user accounts have been changed from
        those recommended in previous versions of this document to
        improve security and maintainability.  See <ulink
	  url="http://openacs.org/forums/message-view?message_id=82934">this
	  thread</ulink> for discussion.</para>
    </note>

  </sect2>


  <sect2 id="install-stuck">
    <title>Getting Help during installation</title>

    <para>
      We'll do our best to assure that following our instructions will get
      you to the promised land. If something goes wrong, don't
      panic. There are plenty of ways to get help. Here are some tips:
    </para>

    <itemizedlist>
      <listitem>
        <para>
          Keep track of the commands you are run and record their output. I
          like to do my installations in a shell inside of emacs
          (<computeroutput>M-x shell</computeroutput>) so that I can save
          the output if needed. An alternative would be to use the
          <computeroutput>script</computeroutput> command.
        </para>
      </listitem>

      <listitem>
        <para>
          We'll point out where the error logs for the various pieces of
          software are. Output from those logs will help us help you. Don't
          worry if you feel overwhelmed by all the information in the error
          logs. Over time, you'll find that they make more and more
          sense. Soon, you'll actually look forward to errors so that you
          can run to the log and diagnose the problem. 
        </para>
      </listitem>

      <listitem>
        <para>
          Search the <ulink url="http://openacs.org/forums/">forums at
            openacs.org</ulink> - you'll often find many people who have
          struggled through the same spot that you're in.
        </para>
      </listitem>

      <listitem>
        <para>
          The bottom of each page has a link to OpenACS.org, where you can post
          comments and read other users comments about the
          contents of the page.
        </para>
      </listitem>

      <listitem>
        <para>
          Ask questions at the irc channel on <ulink url="http://freenode.net">freenode.net</ulink>
          (#openacs). They're knowledgeable and quite friendly
          if you can keep them on topic.
        </para>
      </listitem>

      <listitem>
        <para>
          Post a question on the <ulink
            url="http://openacs.org/forums/">forums</ulink>. Make sure
          you've done a search first. When you do post, be sure to include
          your setup information (OS, etc) as well as the exact commands
          that are failing with the accompanying error.  If
          there's a SQL error in the TCL error or in the log,
          post that too.
        </para>
      </listitem>

      <listitem>
        <para>
          If you find errors in this document or if you have ideas about
          making it better, please post them in our
          <ulink
            url="http://openacs.org/bugtracker/openacs/">BugTracker</ulink>.
        </para>
      </listitem>
    </itemizedlist>
    <para><phrase role="cvstag">($Id: overview.xml,v 1.28 2006/07/17 05:38:38 torbenb Exp $)</phrase></para>
  </sect2>

</sect1>
