test-doc - Weblog Page

Installation Overview

Created by , last modified by Gustaf Neumann 06 Jan 2007, at 04:38 AM

Table of Contents

Basic Steps
Prerequisite Software

by Vinod Kurup

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Engineering Standards

Created by , last modified by Gustaf Neumann 06 Jan 2007, at 04:38 AM

Table of Contents

OpenACS Style Guide
CVS Guidelines
Release Version Numbering
Constraint naming standard
ACS File Naming and Formatting Standards
PL/SQL Standards
Variables
Automated Testing

Advanced Topics

Created by , last modified by Gustaf Neumann 06 Jan 2007, at 04:38 AM

by Joel Aufrecht

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

This tutorial covers topics which are not essential to creating a minimal working package. Each section can be used independently of all of the others; all sections assume that you've completed the basic tutorial.

OpenACS 4.5 Release Notes

Created by , last modified by Gustaf Neumann 06 Jan 2007, at 04:38 AM

by Don Baccus and Vinod Kurup
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff.

This is the official OpenACS 4.5 release. This release has been subjected to an organized test effort, but please bear in mind that we are still in the process of developing testing tools, methodology, and scripts.

Please report bugs using our Software Development Manager at the OpenACS website . The latest information on installing this alpha release under Oracle 8.1.6/7 or PostgreSQL 7.1.* can be found there as well. Currently the toolkit will not install under Oracle 9i due to Oracle having made "delete" an illegal name for PL/SQL procedures and functions.

Some users have reported success running OpenACS 4.5 under PostgreSQL 7.2, but there may still be some undetected problems with this platform.

You may want to begin by reading our installation documentation for Installing on Unix/Linux or Installing on Windows . Note that the Windows documentation is not current for OpenACS 4.5, but an alternative is to use John Sequeira's Oasis VM project .

After installation, the full documentation set can be found by visiting http://[your-host]/doc. Not all pieces are updated for OpenACS 4.5 at this moment.

If you're using Oracle 8.1.6 or 8.1.7 Enterprise Edition you may want to uncomment the SQL that causes InterMedia to keep online searching online while indexing. The feature doesn't exist in Standard Edition and OpenACS 4.5 now defaults to being loadable in SE. Just grep for 'sync' to find the code.

Also be sure to read the documentation in the Site Wide Search package's sql/oracle directory. The APM doesn't execute the SQL for this package, in part due to the fact that some steps need to be run as the Oracle user 'ctxsys'.

If you're using PostgreSQL be sure to read the documentation on installing the Open FTS driver for OpenACS. It's included in the package as a text file and is also summarized at the end of the installation documentation in the section, Set Up OpenFTS . As with the Oracle version, there are steps you must take manually in order to get this feature working.

We now maintain our test results using a custom OpenACS 4.5 package developed by OpenMSG . As can be seen from the notes, there are still some serious outstanding bugs in this release. If you don't like this state of affairs consider volunteering to help out. Just drop the project manager a quick note and you'll be signed up more quickly than you can say "wait! I've changed my mind!"

Backup and Recovery

Created by , last modified by Gustaf Neumann 06 Jan 2007, at 04:38 AM

Table of Contents

Backup Strategy
Manual backup and recovery
Automated Backup
Using CVS for backup-recovery

By Don Baccus with additions by Joel Aufrecht

We will cover some basic backup and recovery strategies. These are intended to be robust but simple enough to set up. For a large scale production site you would probably need to create your own backup strategies (in particular full dumps from oracle, while easy to set up, are far from the best solution).

There are three basic things which need to be backed up, the database data, the server source tree, and the acs-content-repository (which is in the server source tree).

Figure8.1.Backup and Recovery Strategy

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Install a Unix-like system and supporting software

Created by Malte Sussdorff, last modified by Gustaf Neumann 06 Jan 2007, at 04:38 AM

by Joel Aufrecht

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

You will need a computer running a unix-like system with the following software installed:

tdom
tcl --if you plan to use the OpenACS installation script
gmake and the compile and build environment.

BSD Note
BSD users: in most places in these instructions, gmake will work better than make. (more information on FreeBSD installation). Also, fetch is a native replacement for wget.

Note: Instructions for installing tDOM and threaded tcl are included with the AOLserver4 installation instructions, if these are not yet installed.

The following programs may be useful or required for some configurations. They are included in most distributions:

emacs
cvs (and initialize it)
ImageMagick (used by some packages for server side image manipulation)
Aspell (more information on spell-checking)
DocBook and supporting software (and install emacs keybindings for DocBook SGML)
daemontools (install from source)
a Mail Transport Agent, such as exim or sendmail (or install qmail from source)

In order to cut and paste the example code into your shell, you must first do Setting a global shell variable for cut and paste.

To install a machine to the specifications of the Reference Platform, do the walkthrough of the Red Hat 8.0 Install for OpenACS.

Install Red Hat 8/9

Created by , last modified by Gustaf Neumann 06 Jan 2007, at 04:38 AM

by Joel Aufrecht

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

This section takes a blank PC and sets up some supporting software. You should do this section as-is if you have a machine you can reformat and you want to be sure that your installation works and is secure; it should take about an hour. (In my experience, it's almost always a net time savings of several hours to install a new machine from scratch compared to installing each of these packages installed independently.)

The installation guide assumes you have:

A PC with hard drive you can reinstall
Red Hat 8.0 or 9.0 install discs
A CD with the current Security Patches for your version of Red Hat.

The installation guide assumes that you can do the following on your platform:

Adding users, groups, setting passwords
(For Oracle) Starting an X server and running an X program remotely
Basic file management using cp, rm, mv, and cd
Compiling a program using ./config and make.

You can complete this install without the above knowledge, but if anything goes wrong it may take extra time to understand and correct the problem. Some useful UNIX resources.

Unplug the network cable from your computer. We don't want to connect to the network until we're sure the computer is secure. (Wherever you see the word secure, you should always read it as, "secure enough for our purposes, given the amount of work we're willing to exert and the estimated risk and consequences.")
Insert Red Hat 8.0 or 9.0 Disk 1 into the CD-ROM and reboot the computer
At the boot: prompt, press Enter for a graphical install. The text install is fairly different, so if you need to do that instead proceed with caution, because the guide won't match the steps.
Checking the media is probably a waste of time, so when it asks press Tab and then Enter to skip it.
After the graphical introduction page loads, click Next
Choose the language you want to use and then click Next
Select the keyboard layout you will use and Click Next
Choose your mouse type and Click Next
Red Hat has several templates for new computers. We'll start with the "Server" template and then fine-tune it during the rest of the install. Choose Server and click Next.
Reformat the hard drive. If you know what you're doing, do this step on your own. Otherwise: we're going to let the installer wipe out the everything on the main hard drive and then arrange things to its liking.
1. Choose Automatically Partition and click Next
2. Uncheck Review (and modify if needed) the partitions created and click Next
3. On the pop-up window asking "Are you sure you want to do this?" click Yes IF YOU ARE WIPING YOUR HARD DRIVE.
4. Click Next on the boot loader screen
Configure Networking. Again, if you know what you're doing, do this step yourself, being sure to note the firewall holes. Otherwise, follow the instructions in this step to set up a computer directly connected to the internet with a dedicated IP address.
1. DHCP is a system by which a computer that joins a network (such as on boot) can request a temporary IP address and other network information. Assuming the machine has a dedicated IP address (if it doesn't, it will be tricky to access the OpenACS service from the outside world), we're going to set up that address. If you don't know your netmask, 255.255.255.0 is usually a pretty safe guess. Click Edit, uncheck Configure using DHCP and type in your IP and netmask. Click Ok.
2. Type in your host name, gateway, and DNS server(s). Then click Next.
3. We're going to use the firewall template for high security, meaning that we'll block almost all incoming traffic. Then we'll add a few holes to the firewall for services which we need and know are secure. Choose High security level. Check WWW, SSH, and Mail (SMTP). In the Other ports box, enter 443, 8000, 8443. Click Next. Port 443 is for https (http over ssl), and 8000 and 8443 are http and https access to the development server we'll be setting up.
Select any additional languages you want the computer to support and then click Next
Choose your time zone and click Next.
Type in a root password, twice.

On the Package selection page, we're going to uncheck a lot of packages that install software we don't need, and add packages that have stuff we do need. You should install everything we're installing here or the guide may not work for you; you can install extra stuff, or ignore the instructions here to not install stuff, with relative impunity - at worst, you'll introduce a security risk that's still screened by the firewall, or a resource hog. Just don't install a database or web server, because that would conflict with the database and web server we'll install later.

check Editors (this installs emacs),

click Details next to Text-based Internet, check lynx, and click

OK

;

check Authoring and Publishing (this installs docbook),

uncheck Server Configuration Tools,

uncheck Web Server,

uncheck Windows File Server,

check SQL Database Server (this installs PostgreSQL),

check Development Tools (this installs gmake and other build tools),

uncheck Administration Tools, and

uncheck Printing Support.

At the bottom, check Select Individual Packages and click Next

We need to fine-tune the exact list of packages. The same rules apply as in the last step - you can add more stuff, but you shouldn't remove anything the guide adds. We're going to go through all the packages in one big list, so select Flat View and wait. In a minute, a list of packages will appear.

uncheck apmd (monitors power, not very useful for servers),

check ImageMagick (required for the photo-album packages,

uncheckisdn4k-utils (unless you are using isdn, this installs a useless daemon),

check mutt (a mail program that reads Maildir),

uncheck nfs-utils (nfs is a major security risk),

uncheck pam-devel (I don't remember why, but we don't want this),

uncheck portmap,

uncheck postfix (this is an MTA, but we're going to install qmail later),

check postgresql-devel,

uncheck rsh (rsh is a security hole),

uncheck sendmail (sendmail is an insecure MTA; we're going to install qmail instead later),

check tcl (we need tcl), and

uncheck xinetd (xinetd handles incoming tcp connections. We'll install a different, more secure program, ucspi-tcp).

Click


Next

Red Hat isn't completely happy with the combination of packages we've selected, and wants to satisfy some dependencies. Don't let it. On the next screen, choose Ignore Package Dependencies and click Next.
Click Next to start the copying of files.
Wait. Insert Disk 2 when asked.
Wait. Insert Disk 3 when asked.
If you know how to use it, create a boot disk. Since you can also boot into recovery mode with the Install CDs, this is less useful than it used to be, and we won't bother. Select No,I do not want to create a boot disk and click Next.
Click Exit, remove the CD, and watch the computer reboot.
After it finishes rebooting and shows the login prompt, log in:
```
yourserver login: root
Password:
[root root]#
```
Install any security patches. For example, insert your CD with patches, mount it with mount /dev/cdrom, then cd /mnt/cdrom, then rpm -UVH *rpm. Both Red Hat 8.0 and 9.0 have had both kernel and openssl/openssh root exploits, so you should be upgrading all of that. Since you are upgrading the kernel, reboot after this step.

Lock down SSH

SSH is the protocol we use to connect securely to the computer (replacing telnet, which is insecure). sshd is the daemon that listens for incoming ssh connections. As a security precaution, we are now going to tell ssh not to allow anyone to connect directly to this computer as root. Type this into the shell:
```
emacs /etc/ssh/sshd_config
```
Search for the word "root" by typing C-s (that's emacs-speak for control-s) and then root.

Make the following changes:

#Protocol 2,1 to Protocol 2 (this prevents any connections via SSH 1, which is insecure)

#PermitRootLogin yes to PermitRootLogin no (this prevents the root user from logging in remotely via ssh. If you do this, be sure to create a remote access account, such as "remadmin", which you can use to get ssh before using "su" to become root)

#PermitEmptyPasswords no to PermitEmptyPasswords no (this blocks passwordless accounts) and save and exit by typing C-x C-s C-x C-c

Restart sshd so that the change takes effect.
```
service sshd restart
```

Red Hat still installed a few services we don't need, and which can be security holes. Use the service command to turn them off, and then use chkconfig to automatically edit the System V init directories to permanently (The System V init directories are the ones in /etc/rc.d. They consist of a bunch of scripts for starting and stopping programs, and directories of symlinks for each system level indicating which services should be up and down at any given service level. We'll use this system for PostgreSQL, but we'll use daemontools to perform a similar function for AOLserver. (The reason for this discrepencies is that, while daemontools is better, it's a pain in the ass to deal with and nobody's had any trouble leaving PostgreSQL the way it is.)
```
[root root]# service pcmcia stop
[root root]# service netfs stop
[root root]# chkconfig --del pcmcia
[root root]# chkconfig --del netfs
[root root]#
service pcmcia stop
service netfs stop
chkconfig --del pcmcia
chkconfig --del netfs
```
If you installed PostgreSQL, do also service postgresql start and chkconfig --add postgresql.
Plug in the network cable.

Verify that you have connectivity by going to another computer and ssh'ing to yourserver, logging in as remadmin, and promoting yourself to root:

[joeuser@someotherserver]$  ssh remadmin@yourserver.test

The authenticity of host 'yourserver.test (1.2.3.4)' can't be established.
DSA key fingerprint is 10:b9:b6:10:79:46:14:c8:2d:65:ae:c1:61:4b:a5:a5.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'yourserver.test (1.2.3.4)' (DSA) to the list of known hosts.
Password:
Last login: Mon Mar  3 21:15:27 2003 from host-12-01.dsl-sea.seanet.com
[remadmin remadmin]$ su -
Password: 
[root root]#

If you didn't burn a CD of patches and use it, can still download and install the necessary patches. Here's how to do it for the kernel; you should also check for other critical packages.

Upgrade the kernel to fix a security hole. The default Red Hat 8.0 system kernel (2.4.18-14, which you can check with uname -a) has several security problems. Download the new kernel, install it, and reboot.

[root root]# cd /var/tmp
[root tmp]# wget http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm
--20:39:00--  http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm
           => `kernel-2.4.18-27.7.x.i686.rpm'
Resolving updates.redhat.com... done.
Connecting to updates.redhat.com[66.187.232.52]:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 12,736,430 [application/x-rpm]

100%[======================================>] 12,736,430    78.38K/s    ETA 00:00

20:41:39 (78.38 KB/s) - `kernel-2.4.18-27.7.x.i686.rpm' saved [12736430/12736430]

root@yourserver tmp]# rpm -Uvh kernel-2.4.18-27.7.x.i686.rpm
warning: kernel-2.4.18-27.7.x.i686.rpm: V3 DSA signature: NOKEY, key ID db42a60e
Preparing...                ########################################### [100%]
   1:kernel                 ########################################### [100%]
[root tmp]# reboot

Broadcast message from root (pts/0) (Sat May  3 20:46:39 2003):

The system is going down for reboot NOW!
[root tmp]#
cd /var/tmp
wget http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm
rpm -Uvh kernel-2.4.18-27.7.x.i686.rpm
reboot

OpenACS 4.6.3 Release Notes

Created by , last modified by Gustaf Neumann 06 Jan 2007, at 04:38 AM

by Don Baccus
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

This is a final release of OpenACS 4.6.3. This release has been subjected to an organized test effort, but please bear in mind that we are still in the process of developing testing tools, methodology, and scripts.

Please report bugs using our Bug Tracker at the OpenACS website . This version of the OpenACS Toolkit supports PostgreSQL 7.2.3 and 7.3.2, and Oracle 8i. It will not work with Oracle 9i (support is planned for OpenACS 4.7.)

Upgrading from OpenACS 4.x

OpenACS 4.6.3 includes key datamodel changes to acs-kernel and other packages. Your first step after downloading OpenACS 4.6.3 and restarting AOLserver should be to visit the Package Manager, click on the "install packages" link, and select the checkbox to upgrade acs-kernel. After acs-kernel has been upgraded, return to the "install packages" page and select the checkboxes for all other packages you have installed that need upgrading (they are marked "upgrade" rather than "new install") and perform the upgrade step.

After packages have been upgraded, your installation should run without problems.

Upgrade Instructions

You may want to begin by reading our installation documentation for Unix, Windows, and Mac OS X.

After installation, the full documentation set can be found by visiting http://[your-host]/doc. Installation and maintenance documents are current for 4.6.3 but other documentation may lag behind.

If you're using Oracle 8.1.6 or 8.1.7 Enterprise Edition you may want to uncomment the SQL that causes InterMedia to keep online searching online while indexing. The feature doesn't exist in Standard Edition and OpenACS 4.6.3 now defaults to being loadable in SE. Just grep for 'sync' to find the code.

Also be sure to read the documentation in the Site Wide Search package's sql/oracle directory. The APM doesn't execute the SQL for this package, in part due to the fact that some steps need to be run as the Oracle user 'ctxsys'.

If you're using PostgreSQL be sure to read the documentation on installing the Open FTS driver for OpenACS. It's included in the package as a text file and is also summarized at the end of the installation documentation in the section, 4 . As with the Oracle version, there are steps you must take manually in order to get this feature working.

dotLRN 1.0 is an e-learning solution from MIT based on OpenACS 4.6.3 The dotLRN 1.0 testing effort was organized by Bart Teeuwisse and made use of the OpenACS Bug Tracker and OpenACS test servers hosted by Collaboraid .

OpenACS 4.6 Release Notes

Created by , last modified by Gustaf Neumann 06 Jan 2007, at 04:38 AM

by Don Baccus
OpenACS docs are written by the named authors, but may be edited by OpenACS documentation staff.

This is a final release of OpenACS 4.6. This release has been subjected to an organized test effort, but please bear in mind that we are still in the process of developing testing tools, methodology, and scripts.

Please report bugs using our Software Development Manager at the OpenACS website. The latest information on installing this release under Oracle 8.1.6/7 or PostgreSQL 7.1.* can be found there as well. Currently the toolkit will not install under Oracle 9i due to Oracle having made "delete" an illegal name for PL/SQL procedures and functions.

You may want to begin by reading our installation documentation for Installing on Unix/Linux or Installing on Windows. Note that the Windows documentation is not current for OpenACS 4.6, but an alternative is to use John Sequeira's Oasis VM project.

After installation, the full documentation set can be found by visiting http://[your-host]/doc. Not all pieces are updated for OpenACS 4.6 at this moment.

If you're using Oracle 8.1.6 or 8.1.7 Enterprise Edition you may want to uncomment the SQL that causes InterMedia to keep online searching online while indexing. The feature doesn't exist in Standard Edition and OpenACS 4.6 now defaults to being loadable in SE. Just grep for 'sync' to find the code.

Also be sure to read the documentation in the Site Wide Search package's sql/oracle directory. The APM doesn't execute the SQL for this package, in part due to the fact that some steps need to be run as the Oracle user 'ctxsys'.

If you're using PostgreSQL be sure to read the documentation on installing the Open FTS driver for OpenACS. It's included in the package as a text file and is also summarized at the end of the installation documentation in the section, Set Up OpenFTS. As with the Oracle version, there are steps you must take manually in order to get this feature working.

Here are some notes from our testing group. While not quite up to date it should give you some ideas of where things stand.

 Summarised Testing Status

Skin
Minimal
Release w/caution
Comments:

Package: Page
Test Coverage: Minimal
Release w/caution
Comments:

Package: Bboard
Test Coverage: Reasonable
Suggested Status: Alpha
Comments:

Package: Static Pages
Test Coverage: Minimal
Suggested Status: Release w/caution
Comments:

Package: Ticket Tracker
Test Coverage: Reasonable
Suggested Status: Alpha
Comments: Don tested personally

Package: Ticket Tracker Lite
Test Coverage: Unknown
Suggested Status: 
Comments:

Package: Acs-lang
Test Coverage: Reasonable
Suggested Status: Alpha
Comments: Oracle only

Package: Simple-survey
Test Coverage: Reasonable
Suggested Status: Alpha
Comments:

Package: Portal
Test Coverage: Extensive
Suggested Status: Alpha
Comments:

Package: Notes
Test Coverage: Extensive
Suggested Status: Alpha
Comments:

Package: Bookmarks
Test Coverage: Extensive
Suggested Status: Alpha
Comments:

Package: Clickthrough
Test Coverage: Extensive
Suggested Status: Alpha
Comments:

Package: Acs-mail
Test Coverage: Reasonable
Suggested Status: Release w/caution
Comments:

Package: Acs-messaging
Test Coverage: Reasonable
Suggested Status: Release w/caution
Comments:

Package: File manager
Test Coverage: Minimal
Suggested Status: Release w/caution
Comments:

Package: File Storage
Test Coverage: Minimal
Suggested Status: Release w/caution
Comments:

Package: Site-wide-search
Test Coverage: Minimal
Suggested Status: Release w/caution
Comments:

Package: General Comments
Test Coverage: Extensive
Suggested Status: Alpha
Comments:

Package: Acs-events
Test Coverage: None
Suggested Status: 
Comments: Automated Testing

Package: Acs-datetime
Test Coverage: None
Suggested Status: 
Comments: Automated Testing

Package: Acs-tcl
Test Coverage: Reasonable
Suggested Status: Release w/caution
Comments: Automated Testing

Package: Acs-templating
Test Coverage: Reasonable
Suggested Status: Release w/caution
Comments: Automated Testing

Package: Acs-util
Test Coverage: Reasonable
Suggested Status: Release w/caution
Comments: Automated Testing

Package: Acs-Content-repository
Test Coverage: Minimal
Suggested Status: Release w/caution
Comments: Automated Testing

Package: Acs-content
Test Coverage: Minimal
Suggested Status: Release w/caution
Comments: Automated Testing

Package: Acs-kernel
Test Coverage: Reasonable
Suggested Status: Alpha
Comments: Automated Testing

Package: Acs-subsite
Test Coverage: Reasonable
Suggested Status: Alpha
Comments: 

Package: Acs-bootstrap-installer
Test Coverage: Extensive
Suggested Status: Alpha
Comments: Developers have used this extensively

Package: Acs-api-browser
Test Coverage: Minimal
Suggested Status: Release w/caution
Comments: Automated Testing

Package: Acs-workflow
Test Coverage: Minimal
Suggested Status: Release w/caution
Comments: 

Package: calendar
Test Coverage: Minimal
Suggested Status: Alpha
Comments: Don tested personally

For OpenACS Platform Developers

Created by , last modified by Gustaf Neumann 06 Jan 2007, at 04:38 AM

Weblog Page

BSD Note

Audience