- I OpenACS For Everyone
- I.1 High level information: What is OpenACS?
- I.1.1 Overview
- I.1.2 OpenACS Release Notes
- I.2 OpenACS: robust web development framework
- I.2.1 Introduction
- I.2.2 Basic infrastructure
- I.2.3 Advanced infrastructure
- I.2.4 Domain level tools
- I.1 High level information: What is OpenACS?
- II Administrator's Guide
- II.2 Installation Overview
- II.2.1 Basic Steps
- II.2.2 Prerequisite Software
- II.3 Complete Installation
- II.3.1 Install a Unix-like system and supporting software
- II.3.2 Install Oracle 10g XE on debian
- II.3.2.1 Install Oracle 8.1.7
- II.3.3 Install PostgreSQL
- II.3.4 Install AOLserver 4
- II.3.5 Quick Install of OpenACS
- II.3.5.1 Complex Install OpenACS 5.3
- II.3.6 OpenACS Installation Guide for Windows2000
- II.3.7 OpenACS Installation Guide for Mac OS X
- II.4 Configuring a new OpenACS Site
- II.4.1 Installing OpenACS packages
- II.4.2 Mounting OpenACS packages
- II.4.3 Configuring an OpenACS package
- II.4.4 Setting Permissions on an OpenACS package
- II.4.5 How Do I?
- II.4.6 Configure OpenACS look and feel with templates
- II.5 Upgrading
- II.5.1 Overview
- II.5.2 Upgrading 4.5 or higher to 4.6.3
- II.5.3 Upgrading OpenACS 4.6.3 to 5.0
- II.5.4 Upgrading an OpenACS 5.0.0 or greater installation
- II.5.5 Upgrading the OpenACS files
- II.5.6 Upgrading Platform components
- II.6 Production Environments
- II.6.1 Starting and Stopping an OpenACS instance.
- II.6.2 AOLserver keepalive with inittab
- II.6.3 Running multiple services on one machine
- II.6.4 High Availability/High Performance Configurations
- II.6.5 Staged Deployment for Production Networks
- II.6.6 Installing SSL Support for an OpenACS service
- II.6.7 Set up Log Analysis Reports
- II.6.8 External uptime validation
- II.6.9 Diagnosing Performance Problems
- II.7 Database Management
- II.7.1 Running a PostgreSQL database on another server
- II.7.2 Deleting a tablespace
- II.7.3 Vacuum Postgres nightly
- II.8 Backup and Recovery
- II.8.1 Backup Strategy
- II.8.2 Manual backup and recovery
- II.8.3 Automated Backup
- II.8.4 Using CVS for backup-recovery
- II.A Install Red Hat 8/9
- II.B Install additional supporting software
- II.B.1 Unpack the OpenACS tarball
- II.B.2 Initialize CVS (OPTIONAL)
- II.B.3 Add PSGML commands to emacs init file (OPTIONAL)
- II.B.4 Install Daemontools (OPTIONAL)
- II.B.5 Install qmail (OPTIONAL)
- II.B.6 Install Analog web file analyzer
- II.B.7 Install nspam
- II.B.8 Install Full Text Search
- II.B.9 Install Full Text Search using Tsearch2
- II.B.10 Install Full Text Search using OpenFTS (deprecated see tsearch2)
- II.B.11 Install nsopenssl
- II.B.12 Install tclwebtest.
- II.B.13 Install PHP for use in AOLserver
- II.B.14 Install Squirrelmail for use as a webmail system for OpenACS
- II.B.15 Install PAM Radius for use as external authentication
- II.B.16 Install LDAP for use as external authentication
- II.B.17 Install AOLserver 3.3oacs1
- II.C Credits
- II.C.1 Where did this document come from?
- II.C.2 Linux Install Guides
- II.C.3 Security Information
- II.C.4 Resources
- II.2 Installation Overview
- III For OpenACS Package Developers
- III.9 Development Tutorial
- III.9.1 Creating an Application Package
- III.9.2 Setting Up Database Objects
- III.9.3 Creating Web Pages
- III.9.4 Debugging and Automated Testing
- III.10 Advanced Topics
- III.10.1 Write the Requirements and Design Specs
- III.10.2 Add the new package to CVS
- III.10.3 OpenACS Edit This Page Templates
- III.10.4 Adding Comments
- III.10.5 Admin Pages
- III.10.6 Categories
- III.10.7 Profile your code
- III.10.8 Prepare the package for distribution.
- III.10.9 Distributing upgrades of your package
- III.10.10 Notifications
- III.10.11 Hierarchical data
- III.10.12 Using .vuh files for pretty urls
- III.10.13 Laying out a page with CSS instead of tables
- III.10.14 Sending HTML email from your application
- III.10.15 Basic Caching
- III.10.16 Scheduled Procedures
- III.10.17 Enabling WYSIWYG
- III.10.18 Adding in parameters for your package
- III.10.19 Writing upgrade scripts
- III.10.20 Connect to a second database
- III.10.21 Future Topics
- III.11 Development Reference
- III.11.1 OpenACS Packages
- III.11.2 OpenACS Data Models and the Object System
- III.11.3 The Request Processor
- III.11.4 The OpenACS Database Access API
- III.11.5 Using Templates in OpenACS
- III.11.6 Groups, Context, Permissions
- III.11.7 Writing OpenACS Application Pages
- III.11.8 Parties in OpenACS
- III.11.9 OpenACS Permissions Tediously Explained
- III.11.10 Object Identity
- III.11.11 Programming with AOLserver
- III.11.12 Using Form Builder: building html forms dynamically
- III.12 Engineering Standards
- III.12.1 OpenACS Style Guide
- III.12.2 Release Version Numbering
- III.12.3 Constraint naming standard
- III.12.4 ACS File Naming and Formatting Standards
- III.12.5 PL/SQL Standards
- III.12.6 Variables
- III.12.7 Automated Testing
- III.13 CVS Guidelines
- III.13.1 Using CVS with OpenACS
- III.13.2 OpenACS CVS Concepts
- III.13.3 Contributing code back to OpenACS
- III.13.4 Additional Resources for CVS
- III.14 Documentation Standards
- III.14.1 OpenACS Documentation Guide
- III.14.2 Using PSGML mode in Emacs
- III.14.3 Using nXML mode in Emacs
- III.14.4 Detailed Design Documentation Template
- III.14.5 System/Application Requirements Template
- III.15 TCLWebtest
- III.16 Internationalization
- III.16.1 Internationalization and Localization Overview
- III.16.2 How Internationalization/Localization works in OpenACS
- III.16.4 Design Notes
- III.16.5 Translator's Guide
- III.D Using CVS with an OpenACS Site
- III.9 Development Tutorial
- IV For OpenACS Platform Developers
- IV.17 Kernel Documentation
- IV.17.1 Overview
- IV.17.2 Object Model Requirements
- IV.17.3 Object Model Design
- IV.17.4 Permissions Requirements
- IV.17.5 Permissions Design
- IV.17.6 Groups Requirements
- IV.17.7 Groups Design
- IV.17.8 Subsites Requirements
- IV.17.9 Subsites Design Document
- IV.17.10 Package Manager Requirements
- IV.17.11 Package Manager Design
- IV.17.12 Database Access API
- IV.17.13 OpenACS Internationalization Requirements
- IV.17.14 Security Requirements
- IV.17.15 Security Design
- IV.17.16 Security Notes
- IV.17.17 Request Processor Requirements
- IV.17.18 Request Processor Design
- IV.17.19 Documenting Tcl Files: Page Contracts and Libraries
- IV.17.20 Bootstrapping OpenACS
- IV.17.21 External Authentication Requirements
- IV.18 Releasing OpenACS
- IV.18.1 OpenACS Core and .LRN
- IV.18.2 How to Update the OpenACS.org repository
- IV.18.3 How to package and release an OpenACS Package
- IV.18.4 How to Update the translations
- IV.17 Kernel Documentation
- V Tcl for Web Nerds
- V.1 Tcl for Web Nerds Introduction
- V.2 Basic String Operations
- V.3 List Operations
- V.4 Pattern matching
- V.5 Array Operations
- V.6 Numbers
- V.7 Control Structure
- V.8 Scope, Upvar and Uplevel
- V.9 File Operations
- V.10 Eval
- V.11 Exec
- V.12 Tcl for Web Use
- V.13 OpenACS conventions for TCL
- V.14 Solutions
- VI SQL for Web Nerds
- VI.1 SQL Tutorial
- VI.1.1 SQL Tutorial
- VI.1.2 Answers
- VI.2 SQL for Web Nerds Introduction
- VI.3 Data modeling
- VI.3.1 The Discussion Forum -- philg's personal odyssey
- VI.3.2 Data Types (Oracle)
- VI.3.4 Tables
- VI.3.5 Constraints
- VI.4 Simple queries
- VI.5 More complex queries
- VI.6 Transactions
- VI.7 Triggers
- VI.8 Views
- VI.9 Style
- VI.10 Escaping to the procedural world
- VI.11 Trees
- VI.1 SQL Tutorial
II.2.2 Prerequisite Software
OpenACS requires, at a minimum, an operating system, database, and webserver to work. Many additional programs, such as a build environment, Mail Transport Agent, and source control system, are also needed for a fully effective installation.
Table 2.2. Version Compatibility Matrix
|OpenACS Version||3.2.5||4.5||4.6||4.6.1||4.6.2||4.6.3||5.0||5.1||5.2 (core)
|7.3.2 - 7.3.x||No||Yes||No|
|8.2||No||tar: no, CVS: Yes||Yes|
The OpenACS installation instructions assume the operating system and build environment are installed. The instructions explain installation of TCL, tDOM, tclwebtest, a Web Server, a Database, a Process Controller, and Source Control software. The following external links are for reference only.
OpenACS 5.2.3rc1.The OpenACS tarball comprises the core packages and many useful additional packages. This includes a full set of documentation. The tarball works with both PostgreSQL and Oracle. Some scripts require bash shell.
Operating System.OpenACS is designed for a Unix-like system. It is developed primarily in Linux. It can be run on Mac OS X, and in Windows within VMWare.
GNU/Linux.The installation assumes a linux kernel of 2.2.22 or newer, or 2.4.14 or newer.
FreeBSD.FreeBSD guide. The OpenACS Reference Platform uses shell scripts written for bash, which is the standard Linux shell. If you are using a different shell, you will need to substitute your shell's conventions for setting environment variables when appropriate, and install bash to work with the scripts. Substitute
fetchwhen the instructions suggest you use
wgetto download software.
Mac OS X.the section called “OpenACS Installation Guide for Mac OS X”
Windows/VMWare.the section called “OpenACS Installation Guide for Windows2000” The only way to run OpenACS on Windows is through the VMWare emulator. (Please let me know if you have OpenACS running directly in Windows.)
Build Environment.The Reference Platform installation compiles most programs from source code.
glibc 2.2 or newer, REQUIRED.You need recent versions of these libraries for Oracle to work properly. For Unicode support, you need glibc 2.2 or newer. This should be included in your operating system distribution.
GNU Make 3.76.1 or newer, REQUIRED.PostgreSQL and AOLserver require gmake to compile. Note that on most linux distributions, GNU Make is simply named
makeand there is no
gmake, whereas on BSD distributions,
gmakeare different --use gmake.
TCL 8.4.x, REQUIRED.OpenACS is written in TCL, an interpreted language. A threaded version of the TCL interpreter must be installed for OpenACS to work. The TCL interpreter that is included in most standard distributions may not be thread safe.
TCL 8.4.x development headers and libraries, OPTIONAL. The site-wide-search service, OpenFTS, requires these to compile. (Debian users:
apt-get install tcl8.4-dev). You need this to install OpenFTS.
tDOM, REQUIRED.OpenACS 5.2.3rc1 stores queries in XML files, so we use an AOLserver module called tDOM to parse these files. (This replaces libxml2, which was used prior to 4.6.4.)
tclwebtest, OPTIONAL.tclwebtest is a tool for testing web interfaces via tcl scripts.
Web Server.The web server handles incoming HTTP requests, provides a runtime environment for OpenACS's tcl code, connects to the database, sends out HTTP responses, and logs requests and errors. OpenACS uses AOLserver; some people have had success running Apache with mod_nsd.
AOLserver 4.x, REQUIRED.Provides the base HTTP server
Mat Kovach is graciously maintaining an AOLserver distribution that includes all the patches and modules needed to run OpenACS 5.2.3rc1. These instructions will describe how to install using his source distribution. He also has binaries for SuSE 7.3 and OpenBSD 2.8 (and perhaps more to come), currently located at uptime.openacs.org.
It's also possible to download all the pieces and patches yourself:
AOLserver is available at aolserver.com
The OpenACS PostgreSQL driver (nspostgres.so) is available from SourceForge. If you do decide to use nspostgres.so, you have to remember to change the AOLserver config file to point to nspostgres.so instead of postgres.so. This guide uses Mat Kovach's distro (i.e. postgres.so)
The patch that makes
execwork on BSD is available at sourceforge.net
The patch for aolserver 3.x that makes
ns_uuencodework for binary files is available at sourceforge.net
The patch that makes AOLserver 3.x respect the
-gflag is available at sourceforge.net
nsopenssl, OPTIONAL.Provides SSL capabilities for AOLserver. It requires OpenSSL. You need this if you want users to make secure (https) connections to your webserver. aolserver3.x requires nsopenssl 2.1a. aolserver4.x requires nsopenssl3; see aolserver.com for latest release. (home page)
ns_pam 0.1 or newer, OPTIONAL.Provides PAM capabilities for AOLserver. You need this if you want OpenACS users to authenticate through a PAM module (such as RADIUS).
pam_radius 1.3.16, OPTIONAL.Provides RADIUS capabilities for PAM. You need this if you want to use RADIUS authentication via PAM in OpenACS.
ns_ldap 0.r8, OPTIONAL.Provides LDAP capabilities for AOLserver. You need this if you want to use LDAP authentication in OpenACS.
OpenFTS TCL 0.3.2, OPTIONAL.Adds full-text-search to PostgreSQL and includes a driver for AOLserver. You need this if you want users to be able to search for any text on your site. For postgres 7.4.x and higher, full text search is also available via tsearch2.
Analog 5.32 or newer, OPTIONAL.This program examines web server request logs, looks up DNS values, and produces a report. You need this if you want to see how much traffic your site is getting.
Balance 3.11 or newer, OPTIONAL."Balance is a simple but powerful generic tcp proxy with round robin load balancing and failover mechanisms." You need this or something equivalent if you are running a high-availability production site and do not have an external load balancing system.
Database.The data on your site (for example, user names and passwords, calender entries, and notes) is stored in the database. OpenACS separates the database with an abstraction layer, which means that several different databases all function identically. While you can run the core OpenACS on any supported database, not all contributed packages support all databases.
Oracle 8.1.7 (Either this or PostgreSQL is REQUIRED).You can register and download Oracle from Oracle TechNet. You need this if you want to use an Oracle database.
PostgreSQL 7.4.x (Either this or Oracle is REQUIRED).You need this if you want to use a PostgreSQL database.
Process Controller.This is software that initiates other software, and restarts that software if it fails. On Linux, we recommend using Daemontools to control AOLserver and qmail.
Daemontools 0.76, OPTIONAL.You need this if you want AOLserver and qmail to run "supervised," meaning that they are monitored and automatically restarted if they fail. An alternative would be to run the services from inittab.
Mail Transport Agent.A Mail Transport Agent is a program that handles all incoming and outgoing mail. The Reference Platform uses Qmail; any MTA that provides a sendmail wrapper (that is, that can be invoked by calling the sendmail program with the same variables that sendmail expects) can be used.
Netqmail 1.04, OPTIONAL.You need this (or a different Mail Transport Agent) if you want your webserver to send and receive email.
ucspi-tcp 0.88, OPTIONAL.This program listens for incoming TCP connections and hands them to a program. We use it instead of inetd, which is insecure. You need this if you are running qmail.
DocBook, OPTIONAL.(docbook-xml v4.4, docbook-xsl v1.56, libxslt 1.0.21, xsltproc 1.0.21). You need this to write or edit documentation.
Source Control.A Source Control system keeps track of all of the old versions of your files. It lets you recover old files, compare versions of file, and identify specific versions of files. You can use any source control system; the Reference Platform and the OpenACS.org repository (where you can get patched and development code in between releases) use cvs.
cvs 1.11.18, OPTIONAL.cvs is included in most unix distributions. You need this if you want to track old versions of your files, do controlled deployment of code from development to production, or get or contribute development code from openacs.org.