overview.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="install-steps">
<title>Basic Steps</title>
<para>Most of the documentation in this section is kept as a
reference. More up-to-date documentation is in the <ulink
url="http://openacs.org/xowiki/openacs-system-install">install
sections in the Wiki</ulink>.
</para>
<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 macOS 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 eq "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.31 2018/07/04 10:20:42 gustafn Exp $)</phrase></para>
</sect2>
</sect1>
