- This is the place to look if you want to extend OpenACS and build on
- top of what's already here. Here you can find out about the
- guts of the system.
-
by Vinod Kurup
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
@@ -211,4 +211,4 @@
set hostname [ns_info hostname]
#set address [ns_info address]
set address 0.0.0.0
An installation of the OpenACS includes the OpenACS Kernel, some services that
extend the kernel's functionality, and some applications intended for
end-users. Packages function as individual pieces of subsites. A subsite can contain multiple
@@ -88,7 +88,7 @@
packages for other ACS users to download and install.
For a simple illustration of the difference between ACS without APM
(pre-3.3) and ACS with APM (3.3 and beyond), consider a hypothetical ACS
installation that uses only two of the thirty-odd modules available circa ACS
-3.2 (say, bboard and e-commerce):
APM itself is part of a package, the OpenACS Kernel, an OpenACS
service that is the only mandatory component of an OpenACS installation.
Competitive Analysis
The OpenACS is a platform for web-based application software, and any software
platform has the potential to develop problems like those described above.
Fortunately, there are many precedents for systematic solutions,
Index: openacs-4/packages/acs-core-docs/www/apm-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/apm-requirements.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/apm-requirements.html 14 Oct 2003 11:02:57 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/apm-requirements.html 28 Oct 2003 22:07:33 -0000 1.13
@@ -1,4 +1,4 @@
-
by Bryan Quinn and Todd Nightingale
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/backup-recovery.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/backup-recovery.html,v
diff -u -r1.6 -r1.7
--- openacs-4/packages/acs-core-docs/www/backup-recovery.html 21 Oct 2003 10:04:47 -0000 1.6
+++ openacs-4/packages/acs-core-docs/www/backup-recovery.html 28 Oct 2003 22:07:33 -0000 1.7
@@ -1,4 +1,4 @@
-
by Don Baccus
with additions by Joel Aufrecht
@@ -143,7 +143,7 @@
single nightly backup file which is then collected into a
bigger backup file that includes the other parts of the
service (web pages, content, code). To make a new file every
- night, edit the crontab file for service0:
Add this line to the file. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day.
If you plan to back up the whole /var/lib/aolserver/service0 directory, then it would be redundant to keep a history of database backups. In that case, set up the cron job to overwrite the previous backup each time:
On a test service, make sure that your backup-recovery process work. After backing up the database and file system, delete the service as detailed below and then recover it.
Delete the Service
[root@yourserver root]# svc -d /service/service0
+ night, edit the crontab file for service0:
Add this line to the file. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day.
If you plan to back up the whole /var/lib/aolserver/service0 directory, then it would be redundant to keep a history of database backups. In that case, set up the cron job to overwrite the previous backup each time:
On a test service, make sure that your backup-recovery process work. After backing up the database and file system, delete the service as detailed below and then recover it.
by Jon Salz
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/configure.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/configure.html,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/configure.html 14 Oct 2003 11:02:57 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/configure.html 28 Oct 2003 22:07:33 -0000 1.4
@@ -1 +1 @@
-
by Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/db-api-detailed.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/db-api-detailed.html,v
diff -u -r1.14 -r1.15
--- openacs-4/packages/acs-core-docs/www/db-api-detailed.html 21 Oct 2003 10:04:47 -0000 1.14
+++ openacs-4/packages/acs-core-docs/www/db-api-detailed.html 28 Oct 2003 22:07:33 -0000 1.15
@@ -1,4 +1,4 @@
-
By claus@arsdigita.com, with
additions by Roberto
Mello and the OpenACS Community
@@ -31,7 +31,7 @@
In order to separate content and presentation, all OpenACS documentation will be marked up to conform to the
DocBook XML DTD
-
+
This enables us to publish in a variety
of formats and relieves each contributor of the burden of presentation, freeing him to focus
on content and sharing knowledge.
@@ -52,7 +52,7 @@
list of elements and use more exotic features in your
documents. The list is made up of SGML-elements but basically
the same elements are valid in the XML DTD as long as you remember to:
-
+
Always close your tags with corresponding end-tags and to
not use other tag minimization
@@ -98,7 +98,7 @@
The documentation for each package will make up a little "book" that is structured like this
- examples are emphasized:
-
+
book : Docs for one package - templating
@@ -122,20 +122,20 @@
sources of these DocBook documents
to get an idea of how they are tied together.
Headlines, Sections
-
+
Given that your job starts at the sect1-level, all your documents should open with a
<sect1>-tag and end
with the corresponding </sect1>.
-
+
You need to feed every <sect1> two attributes. The first attribute,
id, is standard and can be used with all elements. It comes in very
handy when interlinking between documents (more about this when talking about links in Section�, “Links”).
The value of id has to be unique
throughout the book you're making since the id's in your
sect1's will turn into filenames when the book is parsed into HTML.
-
+
The other attribute is xreflabel. The value of this is the text that will appear
as the link when referring to this sect1.
@@ -150,7 +150,7 @@
</sect1>
-
+
Inside this container your document will be split up into
<sect2>'s,
each with the same requirements - id and xreflabel
@@ -159,7 +159,7 @@
When it comes to naming your
sect2's and below, prefix them with some abbreviation of the id in the sect1 such as requirements-overview.
Code
-
+
For displaying a snippet of code, a filename or anything else you just want to appear as a part of
a sentence, we will use the tag
<computeroutput>.
@@ -169,12 +169,12 @@
<programlisting> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of
automatically.
Links
-
+
Linking falls into two different categories: inside the book you're making and outside:
1. Inside linking, cross-referencing other parts of your book
By having unique id's you can cross-reference any part of your book
with a simple tag, regardless of where that part is.
-
Check out how I link to a subsection of the Developer's Guide:
+
Check out how I link to a subsection of the Developer's Guide:
Put this in your XML:
@@ -212,7 +212,7 @@
packages-looks, the
parser will try its best to explain where the link takes you.
2. Linking outside the documentation
-
+
If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just
a little different
@@ -233,7 +233,7 @@
do it, so if you want to start converting your documents right away, start out with the ones without graphics ;)
-
+
To insert a graphic we use the elements
<mediaobject>,
<imageobject>,
@@ -259,7 +259,7 @@
Put your graphics in a separate directory ("images") and link to them
only with relative paths.
Lists
-
+
Here's how you make the DocBook equivalent of the three usual HTML-lists:
1. How to make an <ul>
Making an unordered list is pretty much like doing the same thing in HTML - if you close your <li>, that is. The only differences are that each list item has to be wrapped in something more, such as
@@ -304,7 +304,7 @@
</variablelist>
Tables
-
+
DocBook supports several types of tables, but in most cases, the
<informaltable>
is enough:
@@ -341,7 +341,7 @@
<table>
for an example.
Emphasis
-
+
Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one -
<emphasis>.
@@ -420,4 +420,4 @@
8/3/2002
Vinod Kurup
0.3
Added OpenACS information, updated tools, added
extra links and added info to the Publishing section.
-
12/24/2001
Roberto Mello
0.2
Changed recommendation from <phrase> to <emphasis role="strong">
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html,v
diff -u -r1.14 -r1.15
--- openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html 21 Oct 2003 10:04:47 -0000 1.14
+++ openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html 28 Oct 2003 22:07:34 -0000 1.15
@@ -1,4 +1,4 @@
-PL/SQL Standards
People have plenty of usernames and passwords already, we
don't want them to have yet another. We want people to be able to
log in to OpenACS with the same password they use to log in to any
other system.
Besides, administrators have better things to do than create
@@ -44,7 +44,7 @@
only one implementation of the authentication API, namly the one
included in OpenACS Core.
Authentication Driver API: The service contract which
authentication drivers implement.
Conceptual Pictures
Authentication:
-
Account Management (NO PICTURE YET)
Batch Synchronization (NO PICTURE YET)
Requirements
New API
Feature
Status
Description
EXT-AUTH-01
A
Extend Authentication/Acct Status API
EXT-AUTH-03
A
Account Creation API
EXT-AUTH-05
A
Password Management API
EXT-AUTH-30
A
Authority Management API
Login
Feature
Status
Description
EXT-AUTH-04
A
Rewrite login, register, and admin pages to use APIs
EXT-AUTH-38
A
ad_form complain feature
EXT-AUTH-19
A
Rewrite password recovery to use API
EXT-AUTH-21
A
Rewrite email verification with API
EXT-AUTH-28
A
Username is email switch
Users will log in using a username, a authority, and a
+
Account Management (NO PICTURE YET)
Batch Synchronization (NO PICTURE YET)
Requirements
New API
Feature
Status
Description
EXT-AUTH-01
A
Extend Authentication/Acct Status API
EXT-AUTH-03
A
Account Creation API
EXT-AUTH-05
A
Password Management API
EXT-AUTH-30
A
Authority Management API
Login
Feature
Status
Description
EXT-AUTH-04
A
Rewrite login, register, and admin pages to use APIs
EXT-AUTH-38
A
ad_form complain feature
EXT-AUTH-19
A
Rewrite password recovery to use API
EXT-AUTH-21
A
Rewrite email verification with API
EXT-AUTH-28
A
Username is email switch
Users will log in using a username, a authority, and a
password. The authority is the source for user/password
verification. OpenACS can be an authority itself.
Each user in OpenACS will belong to exactly one authority, which
can either be the "local" OpenACS users table, in which case the
Index: openacs-4/packages/acs-core-docs/www/filename.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/filename.html,v
diff -u -r1.14 -r1.15
--- openacs-4/packages/acs-core-docs/www/filename.html 21 Oct 2003 10:04:47 -0000 1.14
+++ openacs-4/packages/acs-core-docs/www/filename.html 28 Oct 2003 22:07:34 -0000 1.15
@@ -1,4 +1,4 @@
-
NOTE: Some of the sections of this template may not apply to your
package, e.g. there may be no user-visible UI elements for a component
of the OpenACS Core. Furthermore, it may be easier in some circumstances
Index: openacs-4/packages/acs-core-docs/www/for-everyone.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/for-everyone.html,v
diff -u -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/for-everyone.html 14 Oct 2003 11:02:58 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/for-everyone.html 28 Oct 2003 22:07:34 -0000 1.12
@@ -1 +1 @@
-Part�I.�OpenACS For Everyone
by Rafael H. Schloming and Mark Thomas
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/groups-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-requirements.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/groups-requirements.html 14 Oct 2003 11:02:58 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/groups-requirements.html 28 Oct 2003 22:07:34 -0000 1.13
@@ -1,4 +1,4 @@
-
by Rafael H. Schloming, Mark Thomas
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/i18n-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-requirements.html,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/i18n-requirements.html 14 Oct 2003 11:02:58 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/i18n-requirements.html 28 Oct 2003 22:07:34 -0000 1.4
@@ -1,4 +1,4 @@
-
@@ -38,7 +38,7 @@
which are static and mostly text, it may be easier to create a
new ADP page for each language. In this case, the pages are
distinguished by a file naming convention.
-
Separate Templates for each Locale
If the request processor finds a file named filename.locale.adp, where locale matches the user's locale, it will process that file instead of filename.adp. For example, for a user with locale tl_PH, the file index.tl_PH.adp, if found, will be used instead of index.adp. The locale-specific file should thus contain text in the language appropriate for that locale. The code in the page, however, should still be in English. Message keys are still processed.
Message Keys in Template Files (ADP Files)
+
Separate Templates for each Locale
If the request processor finds a file named filename.locale.adp, where locale matches the user's locale, it will process that file instead of filename.adp. For example, for a user with locale tl_PH, the file index.tl_PH.adp, if found, will be used instead of index.adp. The locale-specific file should thus contain text in the language appropriate for that locale. The code in the page, however, should still be in English. Message keys are still processed.
Message Keys in Template Files (ADP Files)
Internationalizing templates is about replacing human readable
text in a certain language with internal message keys, which
can then be dynamically replaced with real human language in
@@ -101,9 +101,9 @@
Here are a couple of examples. Say we have the following two
parameters, taken directly from the dotlrn package.
-
The value in the rightmost column in the table above is the
value returned by an invocation of parameter::get. Note that
for localization to happen you must use the -localize flag.
@@ -151,7 +151,7 @@
Use the *_pretty version in your ADP page.
To internationalize numbers, use lc_numeric $value, which formats the number using the appropriate decimal point and thousand separator for the locale.
-
Internationalizing Forms
When coding forms, remember to use message keys for each piece of text that is user-visible, including form option labels and button labels.
Internationalizing Existing Packages
Internationalize Message text in ADP and TCL
Acs-lang includes tools to automate some
+
Internationalizing Forms
When coding forms, remember to use message keys for each piece of text that is user-visible, including form option labels and button labels.
Internationalizing Existing Packages
Internationalize Message text in ADP and TCL
Acs-lang includes tools to automate some
internationalization. From
/acs-admin/apm/, select a
package and then click on
@@ -240,9 +240,9 @@
with the appropriate notation for the type of file, and
store the text in the message catalog. You need to run the
process twice, once for ADP files, and once for Tcl files.
-
Internationalize Package Parameters with visible messages
+
Internationalize Package Parameters with visible messages
Find datetime in .xql files. Use command line tools to find suspect SQL code:
grep -r "to_char.*H" *
+
Internationalize Date and Time queries
Find datetime in .xql files. Use command line tools to find suspect SQL code:
grep -r "to_char.*H" *
grep -r "to_date.*H" *
In SQL statements, replace the format string with the ANSI standard format, YYYY-MM-DD HH24:MI:SS and change the field name to *_ansi so that it cannot be confused with previous, improperly formatting fields. For example,
to_char(timestamp,'MM/DD/YYYY HH:MI:SS') as foo_date_pretty
becomes
to_char(timestamp,'YYYY-MM-DD HH24:MI:SS') as foo_date_ansi
In TCL files where the date fields are used, convert the datetime from local server timezone, which is how it's stored in the database, to the user's timezone for display. Do this with the localizing function lc_time_system_to_conn:
set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]
When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with lc_time_conn_to_system.
Index: openacs-4/packages/acs-core-docs/www/index.adp
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/index.adp,v
diff -u -r1.13 -r1.14
--- openacs-4/packages/acs-core-docs/www/index.adp 14 Oct 2003 11:02:58 -0000 1.13
+++ openacs-4/packages/acs-core-docs/www/index.adp 28 Oct 2003 22:07:34 -0000 1.14
@@ -7,9 +7,7 @@
API Browser
<%
# This block of ADP code ensures that the Installer can still serve this
@@ -51,6 +48,7 @@
if { ! $found_p } {
set found_p 1
adp_puts "\n
OpenACS 5.0.0a1.�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.
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.
Linux.�The installation assumes a linux kernel of 2.2.22 or newer, or 2.4.14 or newer.
FreeBSD.�FreeBSD
guide. The Reference Platform uses 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.
Build Environment.�The Reference Platform installation compiles most programs from
@@ -118,4 +118,4 @@
get patched and development code in between releases) use cvs.
cvs 1.11.2, 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.
Daemontools is a collection of programs for controlling
other processes. We use daemontools to run and monitor AOLServer. It is
installed in /package. These commands install daemontools and
svgroup. svgroup is a script for granting permissions, to allow
users other than root to use daemontools for specific
- services.
Install Daemontools
Red Hat
Make sure you have the source tarball in
+ services.
Install Daemontools
Red Hat
Make sure you have the source tarball in
/tmp, or download it. (The -p
flag in mkdir causes all implied directories in the path
to be made as well.)
(Red Hat 9.0: put
Index: openacs-4/packages/acs-core-docs/www/install-full-text-search.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/install-full-text-search.html,v
diff -u -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/install-full-text-search.html 21 Oct 2003 10:04:47 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/install-full-text-search.html 28 Oct 2003 22:07:34 -0000 1.6
@@ -1,4 +1,4 @@
-
If you want full text search, and you are running PostGreSQL, install this module to support FTS. Do this step after you have installed both PostGreSQL and
+
If you want full text search, and you are running PostGreSQL, install this module to support FTS. Do this step after you have installed both PostGreSQL and
Aolserver. You will need the openfts
tarball in /tmp.
Install Tsearch. This is a PostGreSQL module that
OpenFTS requires.
[root@yourserver root]# su - postgres
@@ -74,7 +74,7 @@
make
su postgres
make install
-exit
Install OpenFTS prerequisites in PostGreSQL instance
If you are installing Full Text Search, add required
+exit
Install OpenFTS prerequisites in PostGreSQL instance
If you are installing Full Text Search, add required
packages to the new database. (In order for full text search
to work, you must also install the PostGreSQL
OpenFTS module and prerequisites.)
by Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/install-nsopenssl.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-nsopenssl.html,v
diff -u -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 14 Oct 2003 11:02:58 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 28 Oct 2003 22:07:34 -0000 1.5
@@ -1,4 +1,4 @@
-
This AOLserver module is required if you want people to connect to your site via
https. These commands compile nsopenssl and install it,
along with a tcl helper script to handle https connections.
You will also need ssl certificates. Because those should
@@ -29,4 +29,4 @@
cd nsopenssl-2.1
make OPENSSL=/usr/lib/ssl
cp nsopenssl.so /usr/local/aolserver/bin
-cp https.tcl /usr/local/aolserver/modules/tcl/
+ by Vinod Kurup
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
-
Purpose of this document
-
- This document will describe how to install, configure, and
- maintain an installation of OpenACS 5.0.0a1 on a Unix-like
- system, including all supporting software. All examples
- in this chapter are part of the OpenACS 5.0.0a1-P or
- OpenACS 5.0.0a1-O Reference Platform, which use Red
- Hat 8.0. Differences between the Reference Platform
- and common alternate platforms (Red Hat 9, Debian) are noted where known.
-
Requirements
- You will need a PC (or equivalent) with at least these minimum
- requirements:
-
- If you want to serve pages to people outside of your machine, you'll
- need a network connection of some type.
-
- Running a reliable database-backed web server requires experience
- with the server's environment, in this case UNIX. UNIX is not always
- an intuitive environment and this guide cannot hope to explain every
- nuance. You should be comfortable with the following tasks before
- attempting an installation:
-
- 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.
-
- All of the software that you will need is free and open-source,
- except for Oracle. You can obtain a free copy of Oracle for
- development purposes. This is described in the Acquire Oracle section.
-
Steps involved
- The basic steps to getting OpenACS up and running are:
-
Install an OS
Install a database (Oracle or
- PostgreSQL)
Install a webserver (AOLServer)
Copy the OpenACS files into place and start the OpenACS installer, which will configure a database instance.
How to use this guide
This is text you will see on
- screen, such as a Button or link
- in a radio button list or menu.
This is text that you will type.
This is text from a program or file which you may need to
-examine or edit:
if {$database == "oracle"} {
- set db_password "mysitepassword"
-}
This is text that you will
-see and type in a command shell, including text you may have to
-change. It is followed by a list of just the commands,
-which you can copy and paste.
su - nsadmin
-svc -d /service/server1
-dropdb server1
-createdb server1
What if I get stuck?
- 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:
-
- Keep track of the commands you are run and record their output. I
- like to do my installations in a shell inside of emacs
- (M-x shell) so that I can save
- the output if needed. An alternative would be to use the
- script command.
-
- 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.
-
- Search the bboards at
- openacs.org - you'll often find many people who have
- struggled through the same spot that you're in.
-
- 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.
-
- Ask questions at the irc channel on openprojects.net
- (#openacs). They're knowledgeable and quite friendly
- if you can keep them on topic.
-
- Post a question on the bboards. 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.
-
- If you find errors in this document or if you have ideas about
- making it better, please post them in our
- BugTracker.
-
Is there an easier way?
-
- After reading through this tome, you may ask yourself if there is a
- better way. Well, not quite. Jonathan Marsden has created RPMs (at
- http://www.xc.org)
- for OpenACS 4.5 but there are not yet any for version
- 5.0.0a1. There has been talk about automating the install process,
- but that hasn't happened yet. Stay tuned!
-
-
Where did this document come from?
- This document was created by Vinod Kurup, but it's really
- just plagiarism from a number of documents that came before it. If
- I've used something that you've written without proper credit, let me
- know and I'll fix it right away.
-
Versions 4.6.2 to present were edited by Joel Aufrecht.
-
- Once you get your OS installed, it's imperative that you secure your
- installation. As Jon Griffin repeatedly warns us, "No distribution is
- secure out of the box." The Reference Platform implements
- some basic precautions, but security is a process, not a
- condition. If you are responsible for a computer hooked to the
- internet, you are responsible for learning some rudiments of
- security, such as monitoring the state of a computer,
- maintaining patch levels, and keeping backups. We recommend
- these resources:
-
-
- LPI
- certification exam preps - A series of articles from
- IBM developerworks on basic and intermediate Linux skills
- (requires registration)
-
-
Qmail is a Mail Transfer Agent. It handles incoming and outgoing mail. Install qmail if you want your OpenACS server to send and receive mail, and you don't want to use an alternate MTA.
Install ucspi.�This program handles incoming tcp connections.
+
Qmail is a Mail Transfer Agent. It handles incoming and outgoing mail. Install qmail if you want your OpenACS server to send and receive mail, and you don't want to use an alternate MTA.
Install ucspi.�This program handles incoming tcp connections.
Download ucspi and install it.
(I'm not sure if this next step is 100% necessary, but when I skip it
I get problems. If you get the error 553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1) then you need to do this.) AOLServer sends outgoing mail via the ns_sendmail
command, which pipes a command to the sendmail executable. Or, in our
@@ -35,7 +35,7 @@
send outgoing mail.
by Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
@@ -8,10 +8,25 @@
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.)
Unplug the network cable from your
+ of these packages installed independently.)
The installation guide assumes 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
@@ -39,7 +54,7 @@
Review (and modify if needed) the partitions created and click Next
On the pop-up window asking "Are you sure
you want to do this?" click
Yes
- IF YOU ARE WIPING YOUR HARD DRIVE.
Click Next on the boot loader screen
Configure Networking.
+ IF YOU ARE WIPING YOUR HARD DRIVE.
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.
DHCP is a system by which a computer that
@@ -60,7 +75,7 @@
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
+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. To
@@ -81,9 +96,9 @@
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),
+
check�Editors�(this�installs�emacs),
click�Details�next�to�Text-based�Internet,�check�lynx,�and�click�OK;
-check�Authoring�and�Publishing�(this�installs�docbook),
+check�Authoring�and�Publishing�(this�installs�docbook),
uncheck�Server�Configuration�Tools,
uncheck�Web�Server,
uncheck�Windows�File�Server,
@@ -96,7 +111,7 @@
Flat
View and wait. In a minute, a
list of packages will appear.
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
Index: openacs-4/packages/acs-core-docs/www/kernel-doc.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-doc.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/kernel-doc.html 14 Oct 2003 11:02:58 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/kernel-doc.html 28 Oct 2003 22:07:34 -0000 1.13
@@ -1 +1 @@
-
by Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
@@ -234,4 +234,4 @@
[root@yourserver root]# emacs /etc/cron.daily/analog
by Rafael H. Schloming
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/object-system-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-design.html,v
diff -u -r1.13 -r1.14
--- openacs-4/packages/acs-core-docs/www/object-system-design.html 14 Oct 2003 11:02:58 -0000 1.13
+++ openacs-4/packages/acs-core-docs/www/object-system-design.html 28 Oct 2003 22:07:35 -0000 1.14
@@ -1,4 +1,4 @@
-
by Pete Su,
Michael Yoon,
Richard Li
Index: openacs-4/packages/acs-core-docs/www/object-system-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-requirements.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/object-system-requirements.html 14 Oct 2003 11:02:58 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/object-system-requirements.html 28 Oct 2003 22:07:35 -0000 1.13
@@ -1,4 +1,4 @@
-
By Pete Su
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/objects.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/objects.html,v
diff -u -r1.15 -r1.16
--- openacs-4/packages/acs-core-docs/www/objects.html 21 Oct 2003 10:04:47 -0000 1.15
+++ openacs-4/packages/acs-core-docs/www/objects.html 28 Oct 2003 22:07:35 -0000 1.16
@@ -1,4 +1,4 @@
-
By Pete Su
OpenACS docs are written by the named authors, and may be edited
@@ -80,7 +80,7 @@
Fire up your text editor and open the
ROOT/packages/notes/sql/oracle/notes-create.sql (ROOT/packages/notes/sql/postgresql/notes-create.sql for the PG version) file created
when we created the package. Then, do the following:
-
Describe the new type to the type system
+
Describe the new type to the type system
First, add an entry to the acs_object_types table with the following PL/SQL call:
begin
@@ -140,7 +140,7 @@
because the new type note is a subtype of
acs_object, it will inherit these attributes, so there is
no need for us to define them.
-
Define a table in which to store your objects
+
Define a table in which to store your objects
The next thing we do is make a small modification to the data model to
reflect the fact that each row in the notes table
represents something that is not only an object of type
@@ -165,7 +165,7 @@
use the acs_objects table to find objects will
transparently find any objects that are instances of any subtype of
acs_objects.
-
Define a package for type specific procedures
+
Define a package for type specific procedures
The next step is to define a PL/SQL package for your new type, and
write some basic procedures to create and delete objects. Here is a
package definition for our new type:
@@ -213,7 +213,7 @@
object OBJ was "read only", then any other object that used OBJ as its
context would also be "read only" by default. We'll talk about this more
later.
-
Define a package body for type specific procedures
+
Define a package body for type specific procedures
The PL/SQL package body contains the implementations of the procedures
defined above. The only subtle thing going on here is that we must use
acs_object.new to insert a row into
Index: openacs-4/packages/acs-core-docs/www/openacs-overview.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-overview.html,v
diff -u -r1.9 -r1.10
--- openacs-4/packages/acs-core-docs/www/openacs-overview.html 14 Oct 2003 11:02:58 -0000 1.9
+++ openacs-4/packages/acs-core-docs/www/openacs-overview.html 28 Oct 2003 22:07:35 -0000 1.10
@@ -1,4 +1,4 @@
-
OpenACS (Open Architecture Community System) is an
advanced toolkit for building scalable, community-oriented
web applications. If you're thinking of building an
Index: openacs-4/packages/acs-core-docs/www/openacs-unpack.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-unpack.html,v
diff -u -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/openacs-unpack.html 14 Oct 2003 11:02:58 -0000 1.4
+++ openacs-4/packages/acs-core-docs/www/openacs-unpack.html 28 Oct 2003 22:07:35 -0000 1.5
@@ -1,4 +1,4 @@
-
by Vinod Kurup
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
@@ -244,7 +244,7 @@
CREATE DATABASE
[service0@yourserver service0]$
su - service0
-createdb -E UNICODE service0
Automate daily database Vacuuming. This is a process which cleans out discarded data from the database. A quick way to automate vacuuming is to edit the cron file for the database user.
Add this line to the file. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day.
Automate daily database Vacuuming. This is a process which cleans out discarded data from the database. A quick way to automate vacuuming is to edit the cron file for the database user.
Add this line to the file. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day.
@@ -254,7 +254,7 @@
need to configure a virtual server. The Reference Platform
uses a configuration file included in the OpenACS tarball,
/var/lib/aolserver/service0/etc/config.tcl.
- Open it in an editor to adjust the parameters.
[root@yourserver root]# su - service0
+ Open it in an editor to adjust the parameters.
[root@yourserver root]# su - service0
[service0@yourserver service0]$ cd /var/lib/aolserver/service0/etc
[service0@yourserver etc]# emacs config.tcl
@@ -378,8 +378,8 @@
5.0.0a1 is now up and running!
Install Full Text Search (OPTIONAL). If you have installed OpenFTS and enabled
OpenFTS, you can now install the OpenFTS Driver package and
- Full Text Search Engine package in the OpenACS service.
Next Steps
This is a good time to make a backup of your service. If this is a
+ Full Text Search Engine package in the OpenACS service.
Next Steps
This is a good time to make a backup of your service. If this is a
production site, you should set up automatic nightly backups.
If you want traffic reports, set up analog or another log
processing program.
Follow the instruction on the home page to
change the appearance of your service or add more
- packages. (more information)
Proceed to the tutorial to learn how to develop your own packages.
by Vinod Kurup
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
@@ -1275,4 +1275,4 @@
authorized to do a connect
internal within
svrmgrl to gain full system
- access to the Oracle system.
by Rafael H. Schloming
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/permissions-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-design.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/permissions-design.html 14 Oct 2003 11:02:58 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/permissions-design.html 28 Oct 2003 22:07:35 -0000 1.13
@@ -1,4 +1,4 @@
-
by John Prevost and Rafael H. Schloming
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/permissions-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-requirements.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/permissions-requirements.html 14 Oct 2003 11:02:58 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/permissions-requirements.html 28 Oct 2003 22:07:36 -0000 1.13
@@ -1,4 +1,4 @@
-
by John McClary Prevost
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html,v
diff -u -r1.8 -r1.9
--- openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 21 Oct 2003 10:04:48 -0000 1.8
+++ openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 28 Oct 2003 22:07:36 -0000 1.9
@@ -1,4 +1,4 @@
-
by Vadim Nasardinov. Modified and converted to Docbook XML by Roberto Mello
Overview
The general permissions system has a relatively complex data model in OpenACS 4.x.
@@ -85,7 +85,7 @@
to store permission information explicitly about every object, i.e. if the system has 100,000 and 1,000 users
who have the read privilege on all objects, then we would need to store 100,000,000
entries of the form:
-
Table�11.1.�
object_id
grantee_id
privilege
object_id_1
user_id_1
'read'
object_id_1
user_id_2
'read'
...
object_id_1
user_id_n
'read'
object_id_2
user_id_1
'read'
object_id_2
user_id_2
'read'
...
object_id_2
user_id_n
'read'
...
...
object_id_m
user_id_1
'read'
object_id_m
user_id_2
'read'
...
object_id_m
user_id_n
'read'
+
Table�9.1.�
object_id
grantee_id
privilege
object_id_1
user_id_1
'read'
object_id_1
user_id_2
'read'
...
object_id_1
user_id_n
'read'
object_id_2
user_id_1
'read'
object_id_2
user_id_2
'read'
...
object_id_2
user_id_n
'read'
...
...
object_id_m
user_id_1
'read'
object_id_m
user_id_2
'read'
...
object_id_m
user_id_n
'read'
Although quite feasible, this approach fails to take advantage of the fact
that objects in the system are commonly organized hierarchally,
and permissions usually follow the hierarchical structure, so that if user
@@ -100,7 +100,7 @@
Context Hierarchy
Suppose objects A, B, ...,
and F form the following hierarchy.
-
Table�11.2.�
A
+
Table�9.2.�
A
object_id=10
B
object_id=20
@@ -116,23 +116,23 @@
This can be represented in the acs_objects table
by the following entries:
-
Table�11.3.�
object_id
context_id
20
10
30
10
40
20
50
20
60
30
+
Table�9.3.�
object_id
context_id
20
10
30
10
40
20
50
20
60
30
The first entry tells us that object 20 is the descendant of object 10, and
the third entry shows that object 40 is the descendant of object 20. By
running a CONNECT BY query,
we can compute that object 40 is the second-generation descendant of object 10.
With this in mind, if we want to record the fact that user Joe has the read privilege on objects
A, ..., F, we only need to record one entry in the
acs_permissions table.
-
Table�11.4.�
object
grantee
privilege
A
Joe
read
+
Table�9.4.�
object
grantee
privilege
A
Joe
read
The fact that Joe can also read B, C,
..., and F can be derived by ascertaining that these objects
are children of A by traversing the context hierarchy.
As it turns out, hierarchical queries are expensive. As
Rafael Schloming put it so aptly, Oracle can't deal with hierarchies for shit.
One way to solve this problem is to cache a flattened view of the context tree like so:
-
Table�11.5.�
object
ancestor
n_generations
A
A
0
B
B
0
B
A
1
C
C
0
C
A
1
D
D
0
D
B
1
D
A
2
E
E
0
E
B
1
E
A
2
F
F
0
F
C
1
F
A
2
+
Table�9.5.�
object
ancestor
n_generations
A
A
0
B
B
0
B
A
1
C
C
0
C
A
1
D
D
0
D
B
1
D
A
2
E
E
0
E
B
1
E
A
2
F
F
0
F
C
1
F
A
2
Note that the number of entries in the flattened view grows exponentially with
respect to the depth of the context tree. For instance, if you have a fully
populated binary tree with a depth of n, then the number of entries
@@ -203,7 +203,7 @@
an object's security_inherit_p column to 'f', you can stop permissions
from cascading down the context tree. In the following example, Joe does not have
the read permissions on C and F.
-
Table�11.6.�
+
Table�9.6.�
A object_id=10 readable�by�Joe
@@ -231,7 +231,7 @@
Privileges are also organized hierarchically. In addition to the five main system privileges
defined in the ACS Kernel data model, application developers may define their own. For instance,
the Bboard package defines the following privileges:
-
Table�11.7.�
privilege
create_category
create_forum
create_message
delete_category
delete_forum
delete_message
moderate_forum
read_category
read_forum
read_message
write_category
write_forum
write_message
+
Table�9.7.�
privilege
create_category
create_forum
create_message
delete_category
delete_forum
delete_message
moderate_forum
read_category
read_forum
read_message
write_category
write_forum
write_message
By defining parent-child relationship between privileges, the OpenACS data model
makes it easier for developers to manage permissions. Instead of granting
a user explicit read, write, delete,
@@ -240,7 +240,7 @@
privilege to which the first four privileges are tied. To give
a more detailed example, the Bboard privileges are structured
as follows.
-
Table�11.8.�
admin
create
delete
read
write
moderate forum
create category
create forum
create message
delete category
delete forum
delete message
read category
read forum
read message
write category
write forum
write message
+
Table�9.8.�
admin
create
delete
read
write
moderate forum
create category
create forum
create message
delete category
delete forum
delete message
read category
read forum
read message
write category
write forum
write message
The parent-child relationship between privileges is represented in
the acs_privilege_hierarchy table:
@@ -286,7 +286,7 @@
Party Hierarchy
Now for the third hierarchy playing a promiment role in the permission system. The party
data model is set up as follows.
-
by Vinod Kurup
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
@@ -63,7 +63,7 @@
Change to the postgres user and run ./configure to set the compilation options automatically. This is the point at which you can
configure PostgreSQL in various ways. For example, if you want to
enable
- Unicode support, add the flags --enable-locale and --enable-multibyte. If you want to see what the other possibilities are, run ./configure --help.
+ Unicode support, add the flags --enable-locale and --enable-multibyte. If you want to see what the other possibilities are, run ./configure --help.
[root@yourserver src]# su - postgres
[postgres@yourserver pgsql]$ cd /usr/local/src/postgresql-7.2.4
[postgres@yourserver postgresql-7.2.4]$ ./configure
@@ -295,4 +295,4 @@
PostgreSQL
Performance Tuning
-
by Michael Yoon, Jon Salz and Lars Pind.
OpenACS docs are written by the named authors, and may be edited
@@ -211,4 +211,4 @@
perform lookup by name, they perform a linear lookup, whereas arrays use a
hash table, so ns_sets are slower than arrays when the number of
entries is large.
-
If you plan to write or edit any documentation with emacs, install a
customized emacs configuration file with DocBook commands in the skeleton
directory, so it will be used for all new users. The file also
Index: openacs-4/packages/acs-core-docs/www/psgml-mode.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-mode.html,v
diff -u -r1.14 -r1.15
--- openacs-4/packages/acs-core-docs/www/psgml-mode.html 21 Oct 2003 10:04:48 -0000 1.14
+++ openacs-4/packages/acs-core-docs/www/psgml-mode.html 28 Oct 2003 22:07:36 -0000 1.15
@@ -1,4 +1,4 @@
-
By David Lutterkort
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/release-notes.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/release-notes.html,v
diff -u -r1.17 -r1.18
--- openacs-4/packages/acs-core-docs/www/release-notes.html 21 Oct 2003 10:04:48 -0000 1.17
+++ openacs-4/packages/acs-core-docs/www/release-notes.html 28 Oct 2003 22:07:36 -0000 1.18
@@ -1,4 +1,4 @@
-
This is the first alpha release of OpenACS 5.0.0. This
release has a number of severe bugs, and is not suitable for
production systems. It has passed several release criteria,
@@ -10,7 +10,7 @@
Bug Tracker at the OpenACS website.
You may want to begin by reading our installation documentation for
- Chapter�4, Installing on Unix/Linux. Note that the Windows documentation is
+ Section�, “a Unix-like system”. Note that the Windows documentation is
not current for OpenACS 5.0.0a1, but an alternative is to use John
Sequeira's Oasis VM
project.
@@ -83,4 +83,4 @@
Who's online feature.
Check out the cvs tree. The files must be checked out
through a cvs account with write access. In this example, the
cvs user on openacs.org is implied from the ssh login information
previously set up. It could be overridden via foobar@openacs.org.
@@ -42,4 +42,4 @@
cd /tmp/tarball
rm -rf /tmp/tarball/openacs-4/CVS
tar cz -f dotlrn-2.0.0a1.tar.gz openacs
-
By Pete Su
OpenACS docs are written by the named authors, and may be edited
@@ -13,7 +13,7 @@
diagram summarizes the stages of the request processor assuming a URL
request like http://someserver.com/notes/somepage.adp.
-
The first thing the RP does is to map the given URL to the appropriate
Index: openacs-4/packages/acs-core-docs/www/requirements-template.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/requirements-template.html,v
diff -u -r1.14 -r1.15
--- openacs-4/packages/acs-core-docs/www/requirements-template.html 21 Oct 2003 10:04:48 -0000 1.14
+++ openacs-4/packages/acs-core-docs/www/requirements-template.html 28 Oct 2003 22:07:36 -0000 1.15
@@ -1,4 +1,4 @@
-
by Rafael H. Schloming
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/rp-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-requirements.html,v
diff -u -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/rp-requirements.html 14 Oct 2003 11:02:59 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/rp-requirements.html 28 Oct 2003 22:07:36 -0000 1.12
@@ -1,4 +1,4 @@
-
by Rafael H. Schloming
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/security-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-design.html,v
diff -u -r1.13 -r1.14
--- openacs-4/packages/acs-core-docs/www/security-design.html 14 Oct 2003 11:02:59 -0000 1.13
+++ openacs-4/packages/acs-core-docs/www/security-design.html 28 Oct 2003 22:07:36 -0000 1.14
@@ -1,4 +1,4 @@
-
by Richard Li, Archit Shah
OpenACS docs are written by the named authors, and may be edited
Index: openacs-4/packages/acs-core-docs/www/security-notes.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-notes.html,v
diff -u -r1.14 -r1.15
--- openacs-4/packages/acs-core-docs/www/security-notes.html 21 Oct 2003 10:04:48 -0000 1.14
+++ openacs-4/packages/acs-core-docs/www/security-notes.html 28 Oct 2003 22:07:37 -0000 1.15
@@ -1,4 +1,4 @@
-
by Richard Li
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/security-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-requirements.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/security-requirements.html 14 Oct 2003 11:02:59 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/security-requirements.html 28 Oct 2003 22:07:37 -0000 1.13
@@ -1,4 +1,4 @@
-
by Richard Li
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/software-versions.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/software-versions.html,v
diff -u -r1.6 -r1.7
--- openacs-4/packages/acs-core-docs/www/software-versions.html 21 Oct 2003 10:04:48 -0000 1.6
+++ openacs-4/packages/acs-core-docs/www/software-versions.html 28 Oct 2003 22:07:37 -0000 1.7
@@ -1,4 +1,4 @@
-
by Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
@@ -7,4 +7,4 @@
and webserver. Many additional programs, such as a Mail
Transport Agent and source control system, are also needed for
a fully effective instance.
-
by Rafael H. Schloming
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/subsites-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-requirements.html,v
diff -u -r1.12 -r1.13
--- openacs-4/packages/acs-core-docs/www/subsites-requirements.html 14 Oct 2003 11:02:59 -0000 1.12
+++ openacs-4/packages/acs-core-docs/www/subsites-requirements.html 28 Oct 2003 22:07:37 -0000 1.13
@@ -1,4 +1,4 @@
-
by Rafael H. Schloming and Dennis Gregorovic
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
Index: openacs-4/packages/acs-core-docs/www/subsites.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites.html,v
diff -u -r1.14 -r1.15
--- openacs-4/packages/acs-core-docs/www/subsites.html 21 Oct 2003 10:04:48 -0000 1.14
+++ openacs-4/packages/acs-core-docs/www/subsites.html 28 Oct 2003 22:07:37 -0000 1.15
@@ -1,4 +1,4 @@
-
Documenting Tcl Files: Page Contracts and Libraries
by Jon Salz on 3 July 2000
OpenACS docs are written by the named authors, and may be edited
Index: openacs-4/packages/acs-core-docs/www/templates.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/templates.html,v
diff -u -r1.14 -r1.15
--- openacs-4/packages/acs-core-docs/www/templates.html 21 Oct 2003 10:04:48 -0000 1.14
+++ openacs-4/packages/acs-core-docs/www/templates.html 28 Oct 2003 22:07:37 -0000 1.15
@@ -1,4 +1,4 @@
-
by Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
-
Overview
This tutorial covers topics which are not essential to
+
Overview
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.
How to enforce security so that users can't
change other users records
How to use the content management tables so that
... what?
How to change the default stylesheets for Form
Builder HTML forms.
How to make your package searchable with OpenFTS/Oracle
How to make your package send email notifications
How to prepare pagelets for inclusion in other pages
How and when to put procedures in a tcl procedure library
How to add general_comments to your pages
More on ad_form - data validation, other stuff.
(plan to draw from Jon Griffin's doc)
How and when to implement caching
partialquery in xql
How to use the html/text entry widget to get the
- "does this look right" confirm page
APM package dependencies
Delete with confirmation
We need a way to delete records. We'll create a
+ "does this look right" confirm page
APM package dependencies
Write the Requirements and Design Specs
It's time to document. For the tutorial we'll use
+ pre-written documentation. When creating a package
+ from scratch, start by copying the documentation template from
+ /var/lib/aolserver/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml
+ to
+ yourpackage/www/docs/xml/index.xml.
You then edit that file with emacs to write the
+ requirements and design sections, generate the html, and start
+ coding. Store any supporting files, like page maps or schema
+ diagrams, in the www/doc/xml
+ directory, and store png or jpg versions of supporting files in the
+ www/doc directory.
For this tutorial, you should instead install the
+ pre-written documentation files for the tutorial app. Log in
+ as service0, create the standard
+ directories, and copy the prepared documentation:
[service0@yourserver service0]$ cd /var/lib/aolserver/service0/packages/samplenote/
+[service0@yourserver samplenote]$ mkdir -p www/doc/xml
+[service0@yourserver samplenote]$ cd www/doc/xml
+[service0@yourserver xml]$ cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/samplenote/* .
+[service0@yourserver xml]$
OpenACS uses DocBook for documentation. DocBook is
+ an XML standard for semantic markup of documentation. That
+ means that the tags you use indicate meaning, not intended
+ appearance. The style sheet will determine appearance. You
+ will edit the text in an xml file, and then process the file
+ into html for reading.
Open the file index.xml
+ in emacs. Examine the file. Find the version history (look for the tag
+ <revhistory>). Add a
+ new record to the document version history. Look for the
+ <authorgroup> tag and
+ add yourself as a second author. Save and exit. For tips on
+ editing SGML files in emacs, see OpenACS Documentation Guide
Process the xml file to create html documentation. The
+ html documentation, including supporting files such as pictures,
+ is stored in the www/docs/
+ directory. A Makefile is provided to generate html from the xml, and copy all of the
+ supporting files. If Docbook is set up correctly, all you need
+ to do is:
[service0@yourserver xml]$ make
+cd .. ; /usr/bin/xsltproc ../../../acs-core-docs/www/xml/openacs.xsl xml/index.xml
+Writing requirements-introduction.html for sect1(requirements-introduction)
+Writing requirements-overview.html for sect1(requirements-overview)
+Writing requirements-cases.html for sect1(requirements-cases)
+Writing sample-data.html for sect1(sample-data)
+Writing requirements.html for chapter(requirements)
+Writing design-data-model.html for sect1(design-data-model)
+Writing design-ui.html for sect1(design-ui)
+Writing design-config.html for sect1(design-config)
+Writing design-future.html for sect1(design-future)
+Writing filename.html for chapter(filename)
+Writing user-guide.html for chapter(user-guide)
+Writing admin-guide.html for chapter(admin-guide)
+Writing bi01.html for bibliography
+Writing index.html for book
+[service0@yourserver xml]$
Verify that the documentation was generated and reflects
+ your changes by browsing to http://yoursite:8000/samplenote/doc
Add the new package to CVS
Before you do any more work, make sure that your work is
+ protected by putting it all into cvs. The cvs
+ add command is not recursive, so you'll have to
+ traverse the directory tree manually and add as you go. (More on
+ CVS)
[service0@yourserver xml]$ cd ..
+[service0@yourserver doc]$ cd ..
+[service0@yourserver www]$ cd ..
+[service0@yourserver samplenote]$ cd ..
+[service0@yourserver packages]$ cvs add samplenote/
+Directory /cvsroot/service0/packages/samplenote added to the repository
+[service0@yourserver packages]$ cd samplenote/
+[service0@yourserver samplenote]$ cvs add www
+Directory /cvsroot/service0/packages/samplenote/www added to the repository
+[service0@yourserver samplenote]$ cd www
+[service0@yourserver www]$ cvs add doc
+Directory /cvsroot/service0/packages/samplenote/www/doc added to the repository
+[service0@yourserver www]$ cd doc
+[service0@yourserver doc]$ cvs add *
+cvs add: cannot add special file `CVS'; skipping
+cvs add: scheduling file `admin-guide.html' for addition
+cvs add: scheduling file `bi01.html' for addition
+cvs add: scheduling file `data-model.dia' for addition
+cvs add: scheduling file `data-model.png' for addition
+cvs add: scheduling file `design-config.html' for addition
+cvs add: scheduling file `design-data-model.html' for addition
+cvs add: scheduling file `design-future.html' for addition
+cvs add: scheduling file `design-ui.html' for addition
+cvs add: scheduling file `filename.html' for addition
+cvs add: scheduling file `index.html' for addition
+cvs add: scheduling file `page-map.dia' for addition
+cvs add: scheduling file `page-map.png' for addition
+cvs add: scheduling file `requirements-cases.html' for addition
+cvs add: scheduling file `requirements-introduction.html' for addition
+cvs add: scheduling file `requirements-overview.html' for addition
+cvs add: scheduling file `requirements.html' for addition
+cvs add: scheduling file `sample-data.html' for addition
+cvs add: scheduling file `sample.png' for addition
+cvs add: scheduling file `user-guide.html' for addition
+cvs add: scheduling file `user-interface.dia' for addition
+cvs add: scheduling file `user-interface.png' for addition
+Directory /cvsroot/service0/packages/samplenote/www/doc/xml added to the repository
+cvs add: use 'cvs commit' to add these files permanently
+[service0@yourserver doc]$ cd xml
+[service0@yourserver xml]$ cvs add Makefile index.xml
+cvs add: scheduling file `Makefile' for addition
+cvs add: scheduling file `index.xml' for addition
+cvs add: use 'cvs commit' to add these files permanently
+[service0@yourserver xml]$ cd ../../..
+[service0@yourserver samplenote]$ cvs commit -m "new package"
+cvs commit: Examining .
+cvs commit: Examining www
+cvs commit: Examining www/doc
+cvs commit: Examining www/doc/xml
+RCS file: /cvsroot/service0/packages/samplenote/www/doc/admin-guide.html,v
+done
+Checking in www/doc/admin-guide.html;
+/cvsroot/service0/packages/samplenote/www/doc/admin-guide.html,v <-- admin-guide.html
+initial revision: 1.1
+done
+(many lines omitted)
+[service0@yourserver samplenote]$
Delete with confirmation
We need a way to delete records. We'll create a
recursive confirmation page.
ad_page_contract {
A page that gets confirmation and then delete notes.
@@ -70,7 +180,7 @@
<formtemplate id="note-del-confirm"></formtemplate>
</form>
The ADP is very simple. The
formtemplate tag outputs the HTML
-form generated by the ad_form command with the matching name. Test it by adding the new files in the APM and then deleting a few samplenotes.
General_comments
You can track comments for any ACS Object. Here we'll track
+form generated by the ad_form command with the matching name. Test it by adding the new files in the APM and then deleting a few samplenotes.
General_comments
You can track comments for any ACS Object. Here we'll track
comments for notes. On the notes.tcl/adp pair, which is used to
display individual notes, we want to put a link to add comments at
the bottom of the screen. If there are any comments, we want to
@@ -91,13 +201,13 @@
there are comments. Then you pass the note id, which is also the
acs_object id.
We put our two new variables in the notes.adp
page.
<a href="@comment_add_url@">Add a comment</a>
-@comments_html@
Prepare the package for distribution.
Browse to the package manager. Click on
+@comments_html@
Prepare the package for distribution.
Browse to the package manager. Click on
tutorialapp.
Click on Generate a distribution file
for this package from the
filesystem.
Click on the file size
(37.1KB)
after the label Distribution
File: and save the file to
- /tmp.
by Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
-
Code the data model
We create all database objects with scripts in the
- samplenote/sql/ directory. All
+
Code the data model
We create all database objects with scripts in the
+ myfirstpackage/sql/ directory. All
database scripts are database-specific and are thus in either
- the samplenote/sql/oracle or
- samplenote/sql/postgresql.
- Packages can support Oracle, PostgreSQL, or both.
The first file will be
- samplenote-create.sql. The
+ the myfirstpackage/sql/oracle or
+ myfirstpackage/sql/postgresql.
+ Packages can support Oracle, PostGreSQL, or both. In this
+ tutorial, we'll work only with PostGreSQL
The first file will be
+ myfirstpackage-create.sql. The
package manager requires a file with the name
packagekey-create.sql,
which it will run automatically when the package in installed.
@@ -17,228 +18,82 @@
TABLE command, however, because we want to
integrate our table with the OpenACS system. By making each
record in our table an OpenACS object, we gain access to the
- permissions system as well as some metadata. The downside is
+ permissions system and to services that integrate with OpenACS
+ objects, such as general-comments and notification. The cost
that our table creation code must include several functions and
stored procedures and is fairly complicated even for a simple
- table. A listing is provided below for you to cut and paste.
- Comments are located within the source code, with each comment
- preceeding the relevant code. (More
- info about ACS Objects)
First, create the necessary subdirectories and add them
- cvs as you go.
[service0@yourserver samplenote]$ cd /web/service0/packages/samplenote
-[service0@yourserver samplenote]$ mkdir sql
-[service0@yourserver samplenote]$ cvs add sql
-Directory /cvsroot/service0/packages/samplenote/sql added to the repository
-[service0@yourserver samplenote]$ cd sql/
-[service0@yourserver sql]$ mkdir postgresql
-[service0@yourserver sql]$ cvs add postgresql
-Directory /cvsroot/service0/packages/samplenote/sql/postgresql added to the repository
-[service0@yourserver sql]$ cd postgresql/
We break out the sql commands into several files that can
- be called independently, and then call all of the create files
- from the master create file. The top of each sql file has some
+ table.
There are many kinds of OpenACS objects in the system. (You
+ can see them with select object_type from
+ acs_object_types;.) One such object is the
+ content_item, which is part of the content repository system.
+ We will make our data objects children of the content_item
+ object. Not only will we gain the benefits of both OpenACS
+ Objects and content objects, we can also use some content
+ repository functions to simplify our database creation. (More
+ information about ACS Objects. More information about the
+ Content Repository.)
+
The top of each sql file has some
standard comments, including doc tags such as
@author which will be picked up
by the API browser. The string
$Id$ will automatically be
- expanded when the file is checked in to cvs.
--
--- packages/samplenote/sql/postgresql/samplenote-table-create.sql
---
--- @author rhs@mit.edu
--- @creation-date 2000-10-22
--- @cvs-id $Id$
---
-
-/* Create the table. Each constraint is named to make it easier to
-identify during debugging. The note_id is identical to the object
-id. */
-
-create table samplenote (
- note_id integer constraint samplenote_fk
- references acs_objects(object_id)
- constraint samplenote_pk
- primary key,
- title varchar(255)
- constraint samplenote_title_nn
- not null,
- body varchar(1024)
+select content_type__create_type(
+ 'mfp_note', -- content_type
+ 'content_revision', -- supertype
+ 'MFP Note', -- pretty_name,
+ 'MFP Notes', -- pretty_plural
+ 'mfp_notes', -- table_name
+ 'note_id', -- id_column
+ null -- name_method
);
-
-
-/* Each record in our package is an 'samplenote', and each samplenote
-is an ACS Object. That means that each record in the samplenote table
-has a corresponding record in acs_objects. By making our records ACS
-objects, we gain access to the permissions model and other
-meta-functions. In general, you should make a table an ACS Object
-Type if you expect to apply permissions directly at that level. */
-
-select acs_object_type__create_type (
- ''samplenote'', -- object_type
- ''Sample Note'', -- pretty_name
- ''Sample Notes'', -- pretty_plural
- ''acs_object'', -- supertype
- ''samplenote'', -- table_name
- ''note_id'', -- id_column
- null, -- package_name
- ''f'', -- abstract_p
- null, -- type_extension_table
- ''samplenote__name'' -- name_method
- );
-
Create the file to create the functions used to manipulate records.
The creation script calls a function,
+ content_type__create_type, which
+ in turn creates the necessary database changes to support our data
+ object. Notice the use of "mfp." This token, derived from "My
+ First Package," ensures that our object is unlikely to conflict
+ with objects from other packages.
Create a database file to drop everything if the package
+ is uninstalled.
-- packages/myfirstpackage/sql/myfirstpackage-drop.sql
+-- drop script
--
-- @author rhs@mit.edu
--- @creation-date 2000-10-22
-- @cvs-id $Id$
--
---
-
-/* Since each record is also an Object, we make a creation function
-that will create an object and then use the object id to create a
-record in our table. The function also takes several input variables.
-Title is required
-Body is required
-Creation date is optional and defaults to now
-Creation user, required, is the user id owns the object
-Creation ip is optional
-Context id, required, is the id of the package instance. This allows
-segregation of records by package instance, required to make the package
-"package-aware."
-define_function_args prepares the function to be used by a tcl wrapper function. */
-
-select define_function_args('samplenote__new','note_id,title,body,creation_date,creation_user,creation_ip,context_id');
-
-create or replace function samplenote__new (integer,varchar,varchar,timestamptz,integer,varchar,integer)
+-- THIS SCRIPT IS BROKEN AT THE MOMENT
+create function inline_0 ()
returns integer as '
declare
- p_note_id alias for $1;
- p_title alias for $2;
- p_body alias for $3;
- p_creation_date alias for $4;
- p_creation_user alias for $5;
- p_creation_ip alias for $6;
- p_context_id alias for $7;
- v_samplenote_id int;
+ rec record;
begin
- v_samplenote_id := acs_object__new (
- p_note_id,
- ''samplenote'',
- p_creation_date,
- p_creation_user,
- p_creation_ip,
- p_context_id
- );
- insert into samplenote
- (note_id, title, body)
- values
- (v_samplenote_id, p_title, p_body);
- PERFORM acs_permission__grant_permission(
- v_samplenote_id,
- p_creation_user,
- ''admin''
- );
- return v_samplenote_id;
+ for rec in (select folder_id
+ from cr_folders
+ where package_id in (select package_id
+ from apm_packages
+ where package_key = ''myfirstpackage''))
+ loop
+ perform content_folder__unregister_content_type(rec.folder_id, ''mfp_note'',''t'');
+ end loop;
+ return 0;
end;' language 'plpgsql';
-
-/* The __delete function deletes a record and all related overhead. */
-
+select inline_0();
+drop function inline_0 ();
-select define_function_args('samplenote__delete','note_id');
-create or replace function samplenote__delete (integer)
-returns integer as '
-declare
- p_samplenote_id alias for $1;
-begin
- delete from acs_permissions
- where object_id = p_samplenote_id;
- delete from samplenote
- where note_id = p_samplenote_id;
- raise NOTICE ''Deleting samplenote...'';
- PERFORM acs_object__delete(p_samplenote_id);
- return 0;
-end;' language 'plpgsql';
-
-/* When we created the acs object type above, we specified a
-'name_method'. This is the name of a function that will return the
-name of the object. This is a convention ensuring that all objects
-can be identified. Now we have to build that function. In this case,
-we'll return a field called title as the name. */
-
-select define_function_args('samplenote__name','note_id');
-
-create or replace function samplenote__name (integer)
-returns varchar as '
-declare
- p_samplenote_id alias for $1;
- v_samplenote_name samplenote.title%TYPE;
-begin
- select title into v_samplenote_name
- from samplenote
- where note_id = p_samplenote_id;
- return v_samplenote_name;
-end;
-' language 'plpgsql';
-
Create a database file to drop everything if the package
- is uninstalled.
If there are errors, use them to debug the sql file and try again. If there are errors in the database table creation, you may need to run the drop script to drop the table so that you can recreate it. The drop script will probably have errors since some of the things it's trying to drop may be missing. They can be ignored.
If there are errors creating the functions, you can re-run the function creation file directly after fixing it, because all of the functions are created with create or replace commands. This will also make it easier to fix mistakes within the functions that aren't apparent until the functions are used. And it will make upgrades easier.
Once you get the same output as shown above, test the drop script:
The drop script is a bit hairier than the create script.
Run the create script manually to add your tables and functions.
[service0@yourserver postgresql]$ psql -f myfirstpackage-create.sql
+psql:myfirstpackage-create.sql:14: NOTICE: CREATE TABLE / PRIMARY KEY will create implicit index 'mfp_notes_pkey' for table 'mfp_notes'
+psql:myfirstpackage-create.sql:14: NOTICE: CREATE TABLE will create implicit trigger(s) for FOREIGN KEY check(s)
+ content_type__create_type
+---------------------------
+ 0
+(1 row)
+
+[service0@yourserver postgresql]$
If there are errors, use them to debug the sql file and try again. If there are errors in the database table creation, you may need to run the drop script to drop the table so that you can recreate it. The drop script will probably have errors since some of the things it's trying to drop may be missing. They can be ignored.
Once you get the same output as shown above, test the drop script:
by Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
-
Debugging
Developer Support.�The Developer Support package adds several goodies: debug
+
Debugging
Developer Support.�The Developer Support package adds several goodies: debug
information for every page; the ability to log comments to the
page instead of the error log, and fast user switching so that you
can test pages as anonymous and as dummy users without logging
@@ -24,17 +24,17 @@
?�searches�backward�
/�searches�forward.�
����������
-
Manual testing
Make a list of basic tests to make sure it works
Test Num
Action
Expected Result
001
Browse to the index page while not logged in and
+
Manual testing
Make a list of basic tests to make sure it works
Test Num
Action
Expected Result
001
Browse to the index page while not logged in and
while one or more notes exist.
No edit or delete or add links should appear.
002
Browse to the index page while logged in. An Edit
link should appear. Click on it. Fill out the form and
click Submit.
The text added in the form should be visible on the
index page.
Other things to test: try to delete someone else's
note. Try to delete your own note. Edit your own note.
- Search for a note.
Write automated tests
+ Search for a note.
Write automated tests
by Simon Carstensen
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
-
It seems to me that a lot of
+
It seems to me that a lot of
people have been asking for some guidelines on how to write automated
tests. I've done several tests by now and have found the process to be
extremely easy and useful. It's a joy to work with automated testing
Index: openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html,v
diff -u -r1.6 -r1.7
--- openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html 21 Oct 2003 10:04:48 -0000 1.6
+++ openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html 28 Oct 2003 22:07:37 -0000 1.7
@@ -1,48 +1,57 @@
-
by Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
-
Overview
To start developing new code in OpenACS, we build a new
+
Overview
To start developing new code in OpenACS, we build a new
package. A package is a a discrete collection of web
pages, tcl code, and database tables and procedures. A package
+ with user interface is called an application; a package which provides
+ functions to other packages and has no direct interface, a
+ service. A package
can be installed, upgraded, and removed. It communicates with
other packages through an API. This chapter walks you through the
minimum steps to create a useful package, including writing
documentation, setting up database tables and procedures,
writing web pages, debugging, and automatic regression testing.
-
Before you begin
You will need:
A computer with a working installation of OpenACS
- 4.6. If you don't have this, see Installation Overview.
+
In this tutorial, we will make an application package for
+ displaying a list of text notes.
+
We use the ACS Package Manager (APM) to add, remove, and
upgrade packages. It handles package meta-data, such as lists of
files that belong in the package. Each package is uniquely
identified by a package key. To start developing a new
package, use the APM to create an empty package with our new
- package key, samplenote. This will create
+ package key, myfirstpackage. This will create
the initial directories, meta-information files, and database
entries for a new package. (More info on APM)
-
Fill in the fields listed below. Tab through the rest.
(Some will change automatically. Don't mess with those.)
Package Key:
- samplenote
+ myfirstpackage
Package Name:
- Notes
+ My First Package
Package Plural:
- Notes
+ My First Package
+ Auto-mount URI:
+ myfirstpackage
+
Initial Version:
0.1d
Summary:
This is my first package.
At the bottom, click
Create Package.
This creates a package rooted at
- /web/service0/packages/samplenote.
+ /var/lib/aolserver/service0/packages/myfirstpackage.
This is the "home directory" of our new package, and all
- files in the package will be within this directory.
Mount the package in the site map
In order to see your work in progress, you must create a
+ files in the package will be within this directory.
Mount the package in the site map
In order to see your work in progress, you must create a
map between the URL space of incoming requests and the package.
You do this by mounting the package in the Site Map. This
creates a link between the incoming URL and an
@@ -52,126 +61,16 @@
code and tables. This requires that a package be developed
package-aware. You'll see how to do that
in this tutorial.
Browse to
-http://yourserver.test:8000/admin/site-map/.
Click the new sub
folder link on the top row in the
Site Map table.
Type note
and click New.
This creates a new row called
note. In the new row, click the new
-application link
Type Sample Note where
+application link
Type My First Package where
it says
untitled, choose
-Notes from the drop-down list, and
+My First Package from the drop-down list, and
click New.
By mounting the package, we've caused all requests to
- http://yourserver.test:8000/note
- to be satisfied from the files at /web/service0/packages/samplenote/www.
Write the Requirements and Design Specs
It's time to document. For the tutorial we'll use
- pre-written documentation. When creating a package
- from scratch, start by copying the documentation template from
- /web/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml
- to
- yourpackage/www/docs/xml/index.xml.
You then edit that file with emacs to write the
- requirements and design sections, generate the html, and start
- coding. Store any supporting files, like page maps or schema
- diagrams, in the www/doc/xml
- directory, and store png or jpg versions of supporting files in the
- www/doc directory.
For this tutorial, you should instead install the
- pre-written documentation files for the tutorial app. Log in
- as service0, create the standard
- directories, and copy the prepared documentation:
[service0@yourserver service0]$ cd /web/service0/packages/samplenote/
-[service0@yourserver samplenote]$ mkdir -p www/doc/xml
-[service0@yourserver samplenote]$ cd www/doc/xml
-[service0@yourserver xml]$ cp /web/service0/packages/acs-core-docs/www/files/samplenote/* .
-[service0@yourserver xml]$
OpenACS uses DocBook for documentation. DocBook is
- an XML standard for semantic markup of documentation. That
- means that the tags you use indicate meaning, not intended
- appearance. The style sheet will determine appearance. You
- will edit the text in an xml file, and then process the file
- into html for reading.
Open the file index.xml
- in emacs. Examine the file. Find the version history (look for the tag
- <revhistory>). Add a
- new record to the document version history. Look for the
- <authorgroup> tag and
- add yourself as a second author. Save and exit. For tips on
- editing SGML files in emacs, see OpenACS Documentation Guide
Process the xml file to create html documentation. The
- html documentation, including supporting files such as pictures,
- is stored in the www/docs/
- directory. A Makefile is provided to generate html from the xml, and copy all of the
- supporting files. If Docbook is set up correctly, all you need
- to do is:
[service0@yourserver xml]$ make
-cd .. ; /usr/bin/xsltproc ../../../acs-core-docs/www/xml/openacs.xsl xml/index.xml
-Writing requirements-introduction.html for sect1(requirements-introduction)
-Writing requirements-overview.html for sect1(requirements-overview)
-Writing requirements-cases.html for sect1(requirements-cases)
-Writing sample-data.html for sect1(sample-data)
-Writing requirements.html for chapter(requirements)
-Writing design-data-model.html for sect1(design-data-model)
-Writing design-ui.html for sect1(design-ui)
-Writing design-config.html for sect1(design-config)
-Writing design-future.html for sect1(design-future)
-Writing filename.html for chapter(filename)
-Writing user-guide.html for chapter(user-guide)
-Writing admin-guide.html for chapter(admin-guide)
-Writing bi01.html for bibliography
-Writing index.html for book
-[service0@yourserver xml]$
Verify that the documentation was generated and reflects
- your changes by browsing to http://yoursite:8000/samplenote/doc
Add the new package to CVS
Before you do any more work, make sure that your work is
- protected by putting it all into cvs. The cvs
- add command is not recursive, so you'll have to
- traverse the directory tree manually and add as you go. (More on
- CVS)
[service0@yourserver xml]$ cd ..
-[service0@yourserver doc]$ cd ..
-[service0@yourserver www]$ cd ..
-[service0@yourserver samplenote]$ cd ..
-[service0@yourserver packages]$ cvs add samplenote/
-Directory /cvsroot/service0/packages/samplenote added to the repository
-[service0@yourserver packages]$ cd samplenote/
-[service0@yourserver samplenote]$ cvs add www
-Directory /cvsroot/service0/packages/samplenote/www added to the repository
-[service0@yourserver samplenote]$ cd www
-[service0@yourserver www]$ cvs add doc
-Directory /cvsroot/service0/packages/samplenote/www/doc added to the repository
-[service0@yourserver www]$ cd doc
-[service0@yourserver doc]$ cvs add *
-cvs add: cannot add special file `CVS'; skipping
-cvs add: scheduling file `admin-guide.html' for addition
-cvs add: scheduling file `bi01.html' for addition
-cvs add: scheduling file `data-model.dia' for addition
-cvs add: scheduling file `data-model.png' for addition
-cvs add: scheduling file `design-config.html' for addition
-cvs add: scheduling file `design-data-model.html' for addition
-cvs add: scheduling file `design-future.html' for addition
-cvs add: scheduling file `design-ui.html' for addition
-cvs add: scheduling file `filename.html' for addition
-cvs add: scheduling file `index.html' for addition
-cvs add: scheduling file `page-map.dia' for addition
-cvs add: scheduling file `page-map.png' for addition
-cvs add: scheduling file `requirements-cases.html' for addition
-cvs add: scheduling file `requirements-introduction.html' for addition
-cvs add: scheduling file `requirements-overview.html' for addition
-cvs add: scheduling file `requirements.html' for addition
-cvs add: scheduling file `sample-data.html' for addition
-cvs add: scheduling file `sample.png' for addition
-cvs add: scheduling file `user-guide.html' for addition
-cvs add: scheduling file `user-interface.dia' for addition
-cvs add: scheduling file `user-interface.png' for addition
-Directory /cvsroot/service0/packages/samplenote/www/doc/xml added to the repository
-cvs add: use 'cvs commit' to add these files permanently
-[service0@yourserver doc]$ cd xml
-[service0@yourserver xml]$ cvs add Makefile index.xml
-cvs add: scheduling file `Makefile' for addition
-cvs add: scheduling file `index.xml' for addition
-cvs add: use 'cvs commit' to add these files permanently
-[service0@yourserver xml]$ cd ../../..
-[service0@yourserver samplenote]$ cvs commit -m "new package"
-cvs commit: Examining .
-cvs commit: Examining www
-cvs commit: Examining www/doc
-cvs commit: Examining www/doc/xml
-RCS file: /cvsroot/service0/packages/samplenote/www/doc/admin-guide.html,v
-done
-Checking in www/doc/admin-guide.html;
-/cvsroot/service0/packages/samplenote/www/doc/admin-guide.html,v <-- admin-guide.html
-initial revision: 1.1
-done
-(many lines omitted)
-[service0@yourserver samplenote]$
by Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
-
Build the "Index" page
Each user-visible page in your package has, typically,
+
Build the "Index" page
Each user-visible page in your package has, typically,
three parts. The xql file contains any database queries, the
tcl file holds the procedural logic for the page and does things
like check permissions, invoke the database queries, and modify
@@ -69,7 +69,7 @@
</queryset>
Create the user-visible page.
[service0@yourserver www]$ emacs index.adp
The first line indicates that this page should be rendered within the the master template, which defaults to /web/service0/www/default-master. The second line passes a title variable to the master template. The third line inserts the contents of the variable table_html. The last line is a link to a page we haven't created yet.
<master>
<property name="title">Sample Notes</property>
@table_html@
-<p><a href="note-edit">Add a note</a></p>
Making the APM load your files
Before we can test these files, we have to notify the
+<p><a href="note-edit">Add a note</a></p>
Making the APM load your files
Before we can test these files, we have to notify the
package manager that they exist. (More precisely, the tcl and
adp will work fine as-is, but the xql file will not be
recognized until we tell the APM about it.).
Go to http://yourserver.test:8000/acs-admin/apm
Click on the samplenote link
Click Manage file information
@@ -85,7 +85,7 @@
to load the contents of the XQL into memory so that it can
be used, and to reload it whenever the file is changed.
The watch will last until the server is restarted.
-
Now that the APM is aware of your files, check to make sure that the self-documenting code is working.
Browse to http://yourserver.test:8000/api-doc/
Click Notes 0.1d
Click Content Pages
Click index.tcl and examine the results.
Test the index page
Go to http://yourserver.test:8000/note/. You should see this:
+
Now that the APM is aware of your files, check to make sure that the self-documenting code is working.
Browse to http://yourserver.test:8000/api-doc/
Click Notes 0.1d
Click Content Pages
Click index.tcl and examine the results.
Test the index page
Go to http://yourserver.test:8000/note/. You should see this:
Sample Notes
Your Workspace : Main Site : Sample Note
@@ -94,7 +94,7 @@
Add a note.
foo@yourserver.test
-
Since our table is empty, it's a pretty boring page. So next we'll make it possible to add records.
We'll create a single page to handle both adding and
editing records. In this recursive approach, the same tcl
function can present a blank HTML form, present the same form
pre-loaded with an existing record, and handle the resulting
@@ -173,7 +173,7 @@
title, for both variables but
wrap it in curly brackets for context so that the spaces aren't
interpreted separators. The formtemplate tag outputs the form
- html with the matching name.
Go to the APM as before and reload. Then test all this by going to the package home page and adding and editing a few records.
Adding files to cvs
Put your new work into source control.
[service0@yourserver www]$ cvs add *.adp *.tcl *.xql
+ html with the matching name.
Go to the APM as before and reload. Then test all this by going to the package home page and adding and editing a few records.
by Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
@@ -9,13 +9,13 @@
manual intervention should be required. If you are running
OpenACS prior to 4.5, upgrading will require manual effort.
Checklist
The required platform for OpenACS 4.6 is the same as
4.5, with the excepion of OpenFTS. You now need OpenFTS 0.3.2, not 0.2.
- OpenACS 4.6 does not support PostGreSQL 7.3.
Required for Full Text Search on PostGreSQL: OpenFTS 0.3.2
Overview
OpenACS consists of files and a database schema. The files
in the OpenACS 4.6 tarball include database upgrade scripts. To start the
upgrade, replace your existing files with the new files and
then restart the server. Then, browse to the APM, which will
detect the new packages and offer to run the appropriate database upgrade
scripts. After restarting the server again, the upgrade is
- complete.
OPTIONAL: Upgrade OpenFTS.�OpenACS Full Text Search requires several pieces: the OpenFTS code, some database functions, and the OpenFTS Engine. If you have OpenFTS 0.2, you'll need to upgrade to to OpenFTS 0.3.2. This is backwards-compatible -
+ complete.
OPTIONAL: Upgrade OpenFTS.�OpenACS Full Text Search requires several pieces: the OpenFTS code, some database functions, and the OpenFTS Engine. If you have OpenFTS 0.2, you'll need to upgrade to to OpenFTS 0.3.2. This is backwards-compatible -
completing this step will not break a working OpenFTS Engine from 4.5.
Uninstall the old OpenFTS Engine
Browse to http://yourserver/openfts.
Click Administration.
Click Drop OpenFTS Engine
Build and install the new OpenFTS driver and supporting tcl procedures. (This section of shell code is not fully documented; please exercise care.)
cd /usr/local/src/
@@ -96,4 +96,4 @@
itself, and then come back and upgrade the rest of the
desired packages in a second pass.
Wait a minute, then browse to the package manager, http://yourserver/acs-admin/apm.
Check that the kernel upgrade worked by clicking All and making sure that acs-kernel version is 5.0.0a1.
OPTIONAL: Install the new OpenFTS Engine.�If you want to upgrade the OpenFTS Engine, do these
steps. (You must have already upgraded the OpenFTS driver to
- 0.3.2.)
Browse to http://yourserver/admin/site-map
On the openfts line, click on set parameters.
Change the value of openfts_tcl_src_path from /usr/local/src/Search-OpenFTS-tcl-0.2/ to /usr/local/src/Search-OpenFTS-tcl-0.3.2/
Index: openacs-4/packages/acs-core-docs/www/xml/index.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/index.xml,v
diff -u -r1.16 -r1.17
--- openacs-4/packages/acs-core-docs/www/xml/index.xml 17 Oct 2003 11:15:55 -0000 1.16
+++ openacs-4/packages/acs-core-docs/www/xml/index.xml 28 Oct 2003 22:07:40 -0000 1.17
@@ -8,7 +8,7 @@
]>
- OpenACS Documentation
+ OpenACS Core DocumentationOpenACS For Everyone
@@ -93,33 +93,36 @@
- Section Missing
+ Release Notes Section MissingAdministrator's Guide
-
- Section Missing
+
+
+ Overview Section Missing
-
+
+
Section Missing
+
+
-
- Installing on Unix/Linux
-
+
+ Complete Installation
+ Section Missing
-
- Section Missing
-
-
- Section Missing
+ Section Missing
@@ -134,24 +137,13 @@
Section Missing
-
- Section Missing
-
-
-
-
- Installing on WindowsSection missing
-
-
- Installing on a MacintoshSection missing
-
-
+ Configuring a New ServicePlaceholder
@@ -181,15 +173,15 @@
Section missing
+
+ Section Missing
+ For OpenACS Package Developers
-
- This is the place to look if you want to extend OpenACS and build on
- top of what's already here. Here you can find out about the
- guts of the system.
+ Tutorials and reference material for creating new OpenACS packages.
@@ -274,19 +266,26 @@
Section missing
-Section missing
+ Section missing
-
+
-Section missing
+CVS Section missing'Releasing OpenACS' missing
+
For OpenACS Platform Developers
+
+ Platform Development
+ Information about the internal workings of OpenACS, useful
+ both for modifying the core functionality and for developing new
+ packages.
+ Kernel Documentation
Index: openacs-4/packages/acs-core-docs/www/xml/releasing-openacs.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/releasing-openacs.xml,v
diff -u -r1.1 -r1.2
--- openacs-4/packages/acs-core-docs/www/xml/releasing-openacs.xml 17 Oct 2003 11:15:55 -0000 1.1
+++ openacs-4/packages/acs-core-docs/www/xml/releasing-openacs.xml 28 Oct 2003 22:07:40 -0000 1.2
@@ -2,7 +2,7 @@
+
%myvars;
]>
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml 20 Aug 2003 16:20:18 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml 28 Oct 2003 22:07:40 -0000 1.4
@@ -43,6 +43,135 @@
+
+ Write the Requirements and Design Specs
+ It's time to document. For the tutorial we'll use
+ pre-written documentation. When creating a package
+ from scratch, start by copying the documentation template from
+ /var/lib/aolserver/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml
+ to
+ yourpackage/www/docs/xml/index.xml.
+ You then edit that file with emacs to write the
+ requirements and design sections, generate the html, and start
+ coding. Store any supporting files, like page maps or schema
+ diagrams, in the www/doc/xml
+ directory, and store png or jpg versions of supporting files in the
+ www/doc directory.
+ For this tutorial, you should instead install the
+ pre-written documentation files for the tutorial app. Log in
+ as service0, create the standard
+ directories, and copy the prepared documentation:
+ [service0@yourserver service0]$ cd /var/lib/aolserver/service0/packages/samplenote/
+[service0@yourserver samplenote]$ mkdir -p www/doc/xml
+[service0@yourserver samplenote]$ cd www/doc/xml
+[service0@yourserver xml]$ cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/samplenote/* .
+[service0@yourserver xml]$
+ OpenACS uses DocBook for documentation. DocBook is
+ an XML standard for semantic markup of documentation. That
+ means that the tags you use indicate meaning, not intended
+ appearance. The style sheet will determine appearance. You
+ will edit the text in an xml file, and then process the file
+ into html for reading.
+ Open the file index.xml
+ in emacs. Examine the file. Find the version history (look for the tag
+ <revhistory>). Add a
+ new record to the document version history. Look for the
+ <authorgroup> tag and
+ add yourself as a second author. Save and exit. For tips on
+ editing SGML files in emacs, see
+ Process the xml file to create html documentation. The
+ html documentation, including supporting files such as pictures,
+ is stored in the www/docs/
+ directory. A Makefile is provided to generate html from the xml, and copy all of the
+ supporting files. If Docbook is set up correctly, all you need
+ to do is:
+ [service0@yourserver xml]$ make
+cd .. ; /usr/bin/xsltproc ../../../acs-core-docs/www/xml/openacs.xsl xml/index.xml
+Writing requirements-introduction.html for sect1(requirements-introduction)
+Writing requirements-overview.html for sect1(requirements-overview)
+Writing requirements-cases.html for sect1(requirements-cases)
+Writing sample-data.html for sect1(sample-data)
+Writing requirements.html for chapter(requirements)
+Writing design-data-model.html for sect1(design-data-model)
+Writing design-ui.html for sect1(design-ui)
+Writing design-config.html for sect1(design-config)
+Writing design-future.html for sect1(design-future)
+Writing filename.html for chapter(filename)
+Writing user-guide.html for chapter(user-guide)
+Writing admin-guide.html for chapter(admin-guide)
+Writing bi01.html for bibliography
+Writing index.html for book
+[service0@yourserver xml]$
+ Verify that the documentation was generated and reflects
+ your changes by browsing to http://yoursite:8000/samplenote/doc
+
+
+ Add the new package to CVS
+ Before you do any more work, make sure that your work is
+ protected by putting it all into cvs. The cvs
+ add command is not recursive, so you'll have to
+ traverse the directory tree manually and add as you go. (More on
+ CVS)
+ [service0@yourserver xml]$ cd ..
+[service0@yourserver doc]$ cd ..
+[service0@yourserver www]$ cd ..
+[service0@yourserver samplenote]$ cd ..
+[service0@yourserver packages]$ cvs add samplenote/
+Directory /cvsroot/service0/packages/samplenote added to the repository
+[service0@yourserver packages]$ cd samplenote/
+[service0@yourserver samplenote]$ cvs add www
+Directory /cvsroot/service0/packages/samplenote/www added to the repository
+[service0@yourserver samplenote]$ cd www
+[service0@yourserver www]$ cvs add doc
+Directory /cvsroot/service0/packages/samplenote/www/doc added to the repository
+[service0@yourserver www]$ cd doc
+[service0@yourserver doc]$ cvs add *
+cvs add: cannot add special file `CVS'; skipping
+cvs add: scheduling file `admin-guide.html' for addition
+cvs add: scheduling file `bi01.html' for addition
+cvs add: scheduling file `data-model.dia' for addition
+cvs add: scheduling file `data-model.png' for addition
+cvs add: scheduling file `design-config.html' for addition
+cvs add: scheduling file `design-data-model.html' for addition
+cvs add: scheduling file `design-future.html' for addition
+cvs add: scheduling file `design-ui.html' for addition
+cvs add: scheduling file `filename.html' for addition
+cvs add: scheduling file `index.html' for addition
+cvs add: scheduling file `page-map.dia' for addition
+cvs add: scheduling file `page-map.png' for addition
+cvs add: scheduling file `requirements-cases.html' for addition
+cvs add: scheduling file `requirements-introduction.html' for addition
+cvs add: scheduling file `requirements-overview.html' for addition
+cvs add: scheduling file `requirements.html' for addition
+cvs add: scheduling file `sample-data.html' for addition
+cvs add: scheduling file `sample.png' for addition
+cvs add: scheduling file `user-guide.html' for addition
+cvs add: scheduling file `user-interface.dia' for addition
+cvs add: scheduling file `user-interface.png' for addition
+Directory /cvsroot/service0/packages/samplenote/www/doc/xml added to the repository
+cvs add: use 'cvs commit' to add these files permanently
+[service0@yourserver doc]$ cd xml
+[service0@yourserver xml]$ cvs add Makefile index.xml
+cvs add: scheduling file `Makefile' for addition
+cvs add: scheduling file `index.xml' for addition
+cvs add: use 'cvs commit' to add these files permanently
+[service0@yourserver xml]$ cd ../../..
+[service0@yourserver samplenote]$ cvs commit -m "new package"
+cvs commit: Examining .
+cvs commit: Examining www
+cvs commit: Examining www/doc
+cvs commit: Examining www/doc/xml
+RCS file: /cvsroot/service0/packages/samplenote/www/doc/admin-guide.html,v
+done
+Checking in www/doc/admin-guide.html;
+/cvsroot/service0/packages/samplenote/www/doc/admin-guide.html,v <-- admin-guide.html
+initial revision: 1.1
+done
+(many lines omitted)
+[service0@yourserver samplenote]$
+ Delete with confirmationWe need a way to delete records. We'll create a
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml 20 Aug 2003 16:20:18 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml 28 Oct 2003 22:07:40 -0000 1.4
@@ -14,13 +14,14 @@
Code the data modelWe create all database objects with scripts in the
- samplenote/sql/ directory. All
+ myfirstpackage/sql/ directory. All
database scripts are database-specific and are thus in either
- the samplenote/sql/oracle or
- samplenote/sql/postgresql.
- Packages can support Oracle, PostgreSQL, or both.
+ the myfirstpackage/sql/oracle or
+ myfirstpackage/sql/postgresql.
+ Packages can support Oracle, PostGreSQL, or both. In this
+ tutorial, we'll work only with PostGreSQLThe first file will be
- samplenote-create.sql. The
+ myfirstpackage-create.sql. The
package manager requires a file with the name
packagekey-create.sql,
which it will run automatically when the package in installed.
@@ -31,268 +32,107 @@
TABLE command, however, because we want to
integrate our table with the OpenACS system. By making each
record in our table an OpenACS object, we gain access to the
- permissions system as well as some metadata. The downside is
+ permissions system and to services that integrate with OpenACS
+ objects, such as general-comments and notification. The cost
that our table creation code must include several functions and
stored procedures and is fairly complicated even for a simple
- table. A listing is provided below for you to cut and paste.
- Comments are located within the source code, with each comment
- preceeding the relevant code. (More
- info about ACS Objects)
-
- First, create the necessary subdirectories and add them
- cvs as you go.
- [service0@yourserver samplenote]$ cd /web/service0/packages/samplenote
-[service0@yourserver samplenote]$ mkdir sql
-[service0@yourserver samplenote]$ cvs add sql
-Directory /cvsroot/service0/packages/samplenote/sql added to the repository
-[service0@yourserver samplenote]$ cd sql/
-[service0@yourserver sql]$ mkdir postgresql
-[service0@yourserver sql]$ cvs add postgresql
-Directory /cvsroot/service0/packages/samplenote/sql/postgresql added to the repository
-[service0@yourserver sql]$ cd postgresql/
- We break out the sql commands into several files that can
- be called independently, and then call all of the create files
- from the master create file. The top of each sql file has some
+ table.
+ There are many kinds of OpenACS objects in the system. (You
+ can see them with select object_type from
+ acs_object_types;.) One such object is the
+ content_item, which is part of the content repository system.
+ We will make our data objects children of the content_item
+ object. Not only will we gain the benefits of both OpenACS
+ Objects and content objects, we can also use some content
+ repository functions to simplify our database creation. (More
+ information about ACS Objects. More information about the
+ Content Repository.)
+
+ The top of each sql file has some
standard comments, including doc tags such as
@author which will be picked up
by the API browser. The string
- $Id$ will automatically be
+ $Id:$ will automatically be
expanded when the file is checked in to cvs.
-[service0@yourserver postgresql]$ emacs samplenote-create.sql
+[service0@yourserver postgresql]$ emacs myfirstpackage-create.sqlPaste this into the file and save and close.Database Creation Script - master create file--
--- packages/samplenote/sql/postgresql/samplenote-create.sql
---
-- @author rhs@mit.edu
--- @creation-date 2000-10-22
--- @cvs-id $Id$
+-- @cvs-id $Id:$
--
---
-\i samplenote-table-create.sql
-\i samplenote-functions-create.sql
-
- Create the file to create the database table.
- [service0@yourserver postgresql]$ emacs samplenote-table-create.sql
- Paste this into the file and save and close.
-
- Database Creation Script - table
- --
--- packages/samplenote/sql/postgresql/samplenote-table-create.sql
---
--- @author rhs@mit.edu
--- @creation-date 2000-10-22
--- @cvs-id $Id$
---
-
-/* Create the table. Each constraint is named to make it easier to
-identify during debugging. The note_id is identical to the object
-id. */
-
-create table samplenote (
- note_id integer constraint samplenote_fk
- references acs_objects(object_id)
- constraint samplenote_pk
- primary key,
- title varchar(255)
- constraint samplenote_title_nn
- not null,
- body varchar(1024)
+select content_type__create_type(
+ 'mfp_note', -- content_type
+ 'content_revision', -- supertype
+ 'MFP Note', -- pretty_name,
+ 'MFP Notes', -- pretty_plural
+ 'mfp_notes', -- table_name
+ 'note_id', -- id_column
+ null -- name_method
);
-
-
-/* Each record in our package is an 'samplenote', and each samplenote
-is an ACS Object. That means that each record in the samplenote table
-has a corresponding record in acs_objects. By making our records ACS
-objects, we gain access to the permissions model and other
-meta-functions. In general, you should make a table an ACS Object
-Type if you expect to apply permissions directly at that level. */
-
-select acs_object_type__create_type (
- ''samplenote'', -- object_type
- ''Sample Note'', -- pretty_name
- ''Sample Notes'', -- pretty_plural
- ''acs_object'', -- supertype
- ''samplenote'', -- table_name
- ''note_id'', -- id_column
- null, -- package_name
- ''f'', -- abstract_p
- null, -- type_extension_table
- ''samplenote__name'' -- name_method
- );
- Create the file to create the functions used to manipulate records.
-[service0@yourserver postgresql]$ emacs samplenote-functions-create.sql
- Paste this into the file and save and close.
-
- Database Creation Script - functions
- --
--- packages/samplenote/sql/postgresql/samplenote-functions-create.sql
---
--- @author rhs@mit.edu
--- @creation-date 2000-10-22
--- @cvs-id $Id$
---
---
-
-/* Since each record is also an Object, we make a creation function
-that will create an object and then use the object id to create a
-record in our table. The function also takes several input variables.
-Title is required
-Body is required
-Creation date is optional and defaults to now
-Creation user, required, is the user id owns the object
-Creation ip is optional
-Context id, required, is the id of the package instance. This allows
-segregation of records by package instance, required to make the package
-"package-aware."
-define_function_args prepares the function to be used by a tcl wrapper function. */
-
-select define_function_args('samplenote__new','note_id,title,body,creation_date,creation_user,creation_ip,context_id');
+ The creation script calls a function,
+ content_type__create_type, which
+ in turn creates the necessary database changes to support our data
+ object. Notice the use of "mfp." This token, derived from "My
+ First Package," ensures that our object is unlikely to conflict
+ with objects from other packages.
-create or replace function samplenote__new (integer,varchar,varchar,timestamptz,integer,varchar,integer)
-returns integer as '
-declare
- p_note_id alias for $1;
- p_title alias for $2;
- p_body alias for $3;
- p_creation_date alias for $4;
- p_creation_user alias for $5;
- p_creation_ip alias for $6;
- p_context_id alias for $7;
- v_samplenote_id int;
-begin
- v_samplenote_id := acs_object__new (
- p_note_id,
- ''samplenote'',
- p_creation_date,
- p_creation_user,
- p_creation_ip,
- p_context_id
- );
- insert into samplenote
- (note_id, title, body)
- values
- (v_samplenote_id, p_title, p_body);
- PERFORM acs_permission__grant_permission(
- v_samplenote_id,
- p_creation_user,
- ''admin''
- );
- return v_samplenote_id;
-end;' language 'plpgsql';
-
-/* The __delete function deletes a record and all related overhead. */
-
-
-select define_function_args('samplenote__delete','note_id');
-create or replace function samplenote__delete (integer)
-returns integer as '
-declare
- p_samplenote_id alias for $1;
-begin
- delete from acs_permissions
- where object_id = p_samplenote_id;
- delete from samplenote
- where note_id = p_samplenote_id;
- raise NOTICE ''Deleting samplenote...'';
- PERFORM acs_object__delete(p_samplenote_id);
- return 0;
-end;' language 'plpgsql';
-
-/* When we created the acs object type above, we specified a
-'name_method'. This is the name of a function that will return the
-name of the object. This is a convention ensuring that all objects
-can be identified. Now we have to build that function. In this case,
-we'll return a field called title as the name. */
-
-select define_function_args('samplenote__name','note_id');
-
-create or replace function samplenote__name (integer)
-returns varchar as '
-declare
- p_samplenote_id alias for $1;
- v_samplenote_name samplenote.title%TYPE;
-begin
- select title into v_samplenote_name
- from samplenote
- where note_id = p_samplenote_id;
- return v_samplenote_name;
-end;
-' language 'plpgsql';
-
- Create a database file to drop everything if the package
is uninstalled.
- [service0@yourserver postgresql]$ emacs samplenote-drop.sql
+ [service0@yourserver postgresql]$ emacs myfirstpackage-drop.sqlDatabase deletion script
- -- packages/samplenote/sql/samplenote-drop.sql
+ -- packages/myfirstpackage/sql/myfirstpackage-drop.sql
-- drop script
--
-- @author rhs@mit.edu
--- @creation-date 2000-10-22
--- @cvs-id $Id$
+-- @cvs-id $Id:$
--
-
-/* This script removes from the database everything associated with
-our table. */
-
---drop package, which drops all functions created with define_function_args
-
-select drop_package('samplenote');
-
---drop permissions
-delete from acs_permissions where object_id in (select note_id from samplenote);
-
---drop objects
+-- THIS SCRIPT IS BROKEN AT THE MOMENT
+create function inline_0 ()
+returns integer as '
declare
- object_rec record;
+ rec record;
begin
- for object_rec in select object_id from acs_objects where object_type=''samplenote''
- loop
- perform acs_object__delete( object_rec.object_id );
- end loop;
- return 0;
+ for rec in (select folder_id
+ from cr_folders
+ where package_id in (select package_id
+ from apm_packages
+ where package_key = ''myfirstpackage''))
+ loop
+ perform content_folder__unregister_content_type(rec.folder_id, ''mfp_note'',''t'');
+ end loop;
+ return 0;
end;' language 'plpgsql';
+select inline_0();
+drop function inline_0 ();
---drop table
-drop table samplenote;
-
---drop type
-select acs_object_type__drop_type(
- 'samplenote',
+select content_type__drop_type(
+ 'mfp_notes',
+ 't',
't'
- );
+ );
+
- Add the database files to cvs.
- [service0@yourserver postgresql]$ cvs add *.sql
-cvs add: scheduling file `samplenote-create.sql' for addition
-cvs add: scheduling file `samplenote-drop.sql' for addition
-cvs add: use 'cvs commit' to add these files permanently
-[service0@yourserver samplenote]$ cvs commit -m "new database files"
-cvs commit: Examining .
-cvs commit: Examining sql
-cvs commit: Examining sql/postgresql
-cvs commit: Examining www
-cvs commit: Examining www/doc
-cvs commit: Examining www/doc/xml
-RCS file: /cvsroot/service0/packages/samplenote/sql/postgresql/samplenote-create.sql,v
-done
-(many lines omitted)
-done
-[service0@yourserver samplenote]$
+ The drop script is a bit hairier than the create script.Run the create script manually to add your tables and functions.
- [service0@yourserver samplenote]$ cd sql/postgresql/
-[service0@yourserver postgresql]$ psql -f samplenote-create.sql
+ [service0@yourserver postgresql]$ psql -f myfirstpackage-create.sql
+psql:myfirstpackage-create.sql:14: NOTICE: CREATE TABLE / PRIMARY KEY will create implicit index 'mfp_notes_pkey' for table 'mfp_notes'
+psql:myfirstpackage-create.sql:14: NOTICE: CREATE TABLE will create implicit trigger(s) for FOREIGN KEY check(s)
+ content_type__create_type
+---------------------------
+ 0
+(1 row)
+
[service0@yourserver postgresql]$If there are errors, use them to debug the sql file and try again. If there are errors in the database table creation, you may need to run the drop script to drop the table so that you can recreate it. The drop script will probably have errors since some of the things it's trying to drop may be missing. They can be ignored.
- If there are errors creating the functions, you can re-run the function creation file directly after fixing it, because all of the functions are created with create or replace commands. This will also make it easier to fix mistakes within the functions that aren't apparent until the functions are used. And it will make upgrades easier.Once you get the same output as shown above, test the drop script:
- [service0@yourserver postgresql]$ psql -f samplenote-drop.sql
+ [service0@yourserver postgresql]$ psql -f myfirstpackage-drop.sql
[service0@yourserver postgresql]$Once both scripts are working without errors, run the create script one last time and proceed.
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml,v
diff -u -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml 20 Aug 2003 16:20:18 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml 28 Oct 2003 22:07:40 -0000 1.6
@@ -16,20 +16,27 @@
To start developing new code in OpenACS, we build a new
package. A package is a a discrete collection of web
pages, tcl code, and database tables and procedures. A package
+ with user interface is called an application; a package which provides
+ functions to other packages and has no direct interface, a
+ service. A package
can be installed, upgraded, and removed. It communicates with
other packages through an API. This chapter walks you through the
minimum steps to create a useful package, including writing
documentation, setting up database tables and procedures,
writing web pages, debugging, and automatic regression testing.
+ In this tutorial, we will make an application package for
+ displaying a list of text notes.
+Before you beginYou will need:
- A computer with a working installation of OpenACS
- 4.6. If you don't have this, see .
+ A computer with a working installation of
+ OpenACS. If you don't have this, see .
Example files, which are included in the
standard OpenACS &version; distribution.
@@ -55,7 +62,7 @@
New Package key
- samplenote
+ myfirstpackage
@@ -70,14 +77,16 @@
files that belong in the package. Each package is uniquely
identified by a package key. To start developing a new
package, use the APM to create an empty package with our new
- package key, samplenote. This will create
+ package key, myfirstpackage. This will create
the initial directories, meta-information files, and database
entries for a new package. (More info on APM)
- Browse to http://yourserver:8000/acs-admin/apm.
+ Browse to
+ http://yourserver:8000/acs-admin/apm.
@@ -88,16 +97,20 @@
Package Key:
- samplenote
+ myfirstpackagePackage Name:
- Notes
+ My First PackagePackage Plural:
- Notes
+ My First Package
+ Auto-mount URI:
+ myfirstpackage
+
+ Initial Version:
0.1d
@@ -111,7 +124,7 @@
This creates a package rooted at
- /web/service0/packages/samplenote.
+ /var/lib/aolserver/service0/packages/myfirstpackage.
This is the "home directory" of our new package, and all
files in the package will be within this directory.
@@ -131,7 +144,8 @@
in this tutorial.
Browse to
-http://yourserver.test:8000/admin/site-map/.
+http://yourserver.test:8000/admin/site-map/.
Click the new sub
@@ -143,144 +157,15 @@
This creates a new row called
note. In the new row, click the new
application link
- Type Sample Note where
+ Type My First Package where
it says
untitled, choose
-Notes from the drop-down list, and
+My First Package from the drop-down list, and
click New.
By mounting the package, we've caused all requests to
- http://yourserver.test:8000/note
- to be satisfied from the files at /web/service0/packages/samplenote/www.
+ http://yourserver.test:8000/myfirstpackage
+ to be satisfied from the files at /var/lib/aolserver/service0/packages/myfirstpackage/www.
-
- Write the Requirements and Design Specs
- It's time to document. For the tutorial we'll use
- pre-written documentation. When creating a package
- from scratch, start by copying the documentation template from
- /web/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml
- to
- yourpackage/www/docs/xml/index.xml.
- You then edit that file with emacs to write the
- requirements and design sections, generate the html, and start
- coding. Store any supporting files, like page maps or schema
- diagrams, in the www/doc/xml
- directory, and store png or jpg versions of supporting files in the
- www/doc directory.
- For this tutorial, you should instead install the
- pre-written documentation files for the tutorial app. Log in
- as service0, create the standard
- directories, and copy the prepared documentation:
- [service0@yourserver service0]$ cd /web/service0/packages/samplenote/
-[service0@yourserver samplenote]$ mkdir -p www/doc/xml
-[service0@yourserver samplenote]$ cd www/doc/xml
-[service0@yourserver xml]$ cp /web/service0/packages/acs-core-docs/www/files/samplenote/* .
-[service0@yourserver xml]$
- OpenACS uses DocBook for documentation. DocBook is
- an XML standard for semantic markup of documentation. That
- means that the tags you use indicate meaning, not intended
- appearance. The style sheet will determine appearance. You
- will edit the text in an xml file, and then process the file
- into html for reading.
- Open the file index.xml
- in emacs. Examine the file. Find the version history (look for the tag
- <revhistory>). Add a
- new record to the document version history. Look for the
- <authorgroup> tag and
- add yourself as a second author. Save and exit. For tips on
- editing SGML files in emacs, see
- Process the xml file to create html documentation. The
- html documentation, including supporting files such as pictures,
- is stored in the www/docs/
- directory. A Makefile is provided to generate html from the xml, and copy all of the
- supporting files. If Docbook is set up correctly, all you need
- to do is:
- [service0@yourserver xml]$ make
-cd .. ; /usr/bin/xsltproc ../../../acs-core-docs/www/xml/openacs.xsl xml/index.xml
-Writing requirements-introduction.html for sect1(requirements-introduction)
-Writing requirements-overview.html for sect1(requirements-overview)
-Writing requirements-cases.html for sect1(requirements-cases)
-Writing sample-data.html for sect1(sample-data)
-Writing requirements.html for chapter(requirements)
-Writing design-data-model.html for sect1(design-data-model)
-Writing design-ui.html for sect1(design-ui)
-Writing design-config.html for sect1(design-config)
-Writing design-future.html for sect1(design-future)
-Writing filename.html for chapter(filename)
-Writing user-guide.html for chapter(user-guide)
-Writing admin-guide.html for chapter(admin-guide)
-Writing bi01.html for bibliography
-Writing index.html for book
-[service0@yourserver xml]$
- Verify that the documentation was generated and reflects
- your changes by browsing to http://yoursite:8000/samplenote/doc
-
-
- Add the new package to CVS
- Before you do any more work, make sure that your work is
- protected by putting it all into cvs. The cvs
- add command is not recursive, so you'll have to
- traverse the directory tree manually and add as you go. (More on
- CVS)
- [service0@yourserver xml]$ cd ..
-[service0@yourserver doc]$ cd ..
-[service0@yourserver www]$ cd ..
-[service0@yourserver samplenote]$ cd ..
-[service0@yourserver packages]$ cvs add samplenote/
-Directory /cvsroot/service0/packages/samplenote added to the repository
-[service0@yourserver packages]$ cd samplenote/
-[service0@yourserver samplenote]$ cvs add www
-Directory /cvsroot/service0/packages/samplenote/www added to the repository
-[service0@yourserver samplenote]$ cd www
-[service0@yourserver www]$ cvs add doc
-Directory /cvsroot/service0/packages/samplenote/www/doc added to the repository
-[service0@yourserver www]$ cd doc
-[service0@yourserver doc]$ cvs add *
-cvs add: cannot add special file `CVS'; skipping
-cvs add: scheduling file `admin-guide.html' for addition
-cvs add: scheduling file `bi01.html' for addition
-cvs add: scheduling file `data-model.dia' for addition
-cvs add: scheduling file `data-model.png' for addition
-cvs add: scheduling file `design-config.html' for addition
-cvs add: scheduling file `design-data-model.html' for addition
-cvs add: scheduling file `design-future.html' for addition
-cvs add: scheduling file `design-ui.html' for addition
-cvs add: scheduling file `filename.html' for addition
-cvs add: scheduling file `index.html' for addition
-cvs add: scheduling file `page-map.dia' for addition
-cvs add: scheduling file `page-map.png' for addition
-cvs add: scheduling file `requirements-cases.html' for addition
-cvs add: scheduling file `requirements-introduction.html' for addition
-cvs add: scheduling file `requirements-overview.html' for addition
-cvs add: scheduling file `requirements.html' for addition
-cvs add: scheduling file `sample-data.html' for addition
-cvs add: scheduling file `sample.png' for addition
-cvs add: scheduling file `user-guide.html' for addition
-cvs add: scheduling file `user-interface.dia' for addition
-cvs add: scheduling file `user-interface.png' for addition
-Directory /cvsroot/service0/packages/samplenote/www/doc/xml added to the repository
-cvs add: use 'cvs commit' to add these files permanently
-[service0@yourserver doc]$ cd xml
-[service0@yourserver xml]$ cvs add Makefile index.xml
-cvs add: scheduling file `Makefile' for addition
-cvs add: scheduling file `index.xml' for addition
-cvs add: use 'cvs commit' to add these files permanently
-[service0@yourserver xml]$ cd ../../..
-[service0@yourserver samplenote]$ cvs commit -m "new package"
-cvs commit: Examining .
-cvs commit: Examining www
-cvs commit: Examining www/doc
-cvs commit: Examining www/doc/xml
-RCS file: /cvsroot/service0/packages/samplenote/www/doc/admin-guide.html,v
-done
-Checking in www/doc/admin-guide.html;
-/cvsroot/service0/packages/samplenote/www/doc/admin-guide.html,v <-- admin-guide.html
-initial revision: 1.1
-done
-(many lines omitted)
-[service0@yourserver samplenote]$
-
Index: openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml,v
diff -u -r1.9 -r1.10
--- openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml 14 Oct 2003 11:00:53 -0000 1.9
+++ openacs-4/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml 28 Oct 2003 22:07:41 -0000 1.10
@@ -33,7 +33,7 @@
You may want to begin by reading our installation documentation for
- . Note that the Windows documentation is
+ . Note that the Windows documentation is
not current for OpenACS &version;, but an alternative is to use John
Sequeira's Oasis VM
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml,v
diff -u -r1.9 -r1.10
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml 20 Aug 2003 16:20:18 -0000 1.9
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml 28 Oct 2003 22:07:41 -0000 1.10
@@ -4,7 +4,7 @@
%myvars;
]>
-
+Credits
@@ -65,4 +65,239 @@
($Id$)
-
+
+ Where did this document come from?
+
+ This document was created by Vinod Kurup, but it's really
+ just plagiarism from a number of documents that came before it. If
+ I've used something that you've written without proper credit, let me
+ know and I'll fix it right away.
+
+ Versions 4.6.2 to present were edited by Joel Aufrecht.
+
+
+ These are a few of my sources:
+
+
+ ArsDigita installation guide
+
+
+
+ OpenACS 3.x installation guide
+
+
+
+ Gilbert Wong's FreeBSD
+ installation guide
+
+
+
+ Vinod Kurup's Brief OpenACS4
+ installation guide
+
+
+
+ Joel
+ Aufrecht's OpenACS 4.5 Quick Guide.
+
+
+
+
+ Please also see the section for more acknowledgements.
+
+
+
+
+ Linux Install Guides
+
+ Here's a list of some helpful documentation for various OS's
+
+
+
+
+ Painless Debian
+ GNU/Linux by Stephen van Egmond
+
+
+
+
+ Official
+ Debian Guide
+
+
+
+
+
+ RedHat
+
+
+
+
+
+ Mandrake
+
+
+
+
+
+ SuSE
+
+
+
+
+
+
+
+ Security Information
+
+ Once you get your OS installed, it's imperative that you secure your
+ installation. As Jon Griffin repeatedly warns us, "No distribution is
+ secure out of the box." The Reference Platform implements
+ some basic precautions, but security is a process, not a
+ condition. If you are responsible for a computer hooked to the
+ internet, you are responsible for learning some rudiments of
+ security, such as monitoring the state of a computer,
+ maintaining patch levels, and keeping backups. We recommend
+ these resources:
+
+
+
+
+
+ Securing and Optimizing Linux - version 2.0
+
+
+
+ Jon
+ Griffin's notes
+
+
+ Linux Administrators
+ Security Guide
+
+
+ Installation
+ of a Secure Webserver
+
+
+
+ Bruce
+ Schneier's Crypto-Gram, especially The
+ security patch treadmill and Monitoring First.
+
+
+
+
+
+
+ Resources
+
+
+ Here are some resources that OpenACS users have found useful.
+
+
+
+ Books
+
+
+
+
+ Philip
+ and Alex's Guide to Web Publishing - A very readable
+ guide to database-backed community websites.
+
+
+
+
+
+ UNIX
+ Power Tools - An excellent introduction to the
+ command line tools and basic programs of UNIX
+
+
+
+
+
+ UNIX
+ System Administration Handbook (formerly the "red book"
+ - now the "purple" book)
+
+
+
+
+
+ UNIX
+ System Administrator's Bible - (LePage and Iarerra 1998;
+ IDG)
+
+
+
+
+
+ Running
+ Linux
+
+ Learning
+ Gnu Emacs
+
+
+
+ Linux
+ in a Nutshell
+
+
+
+
+
+ Web Sites
+
+
+
+
+ The UNIX
+ Reference Desk
+
+
+
+
+
+ The Linux Documentation
+ Project
+
+
+
+
+
+ LPI
+ certification exam preps - A series of articles from
+ IBM developerworks on basic and intermediate Linux skills
+ (requires registration)
+
+
+
+
+
+
+
+
+
+
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml,v
diff -u -r1.9 -r1.10
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml 20 Aug 2003 16:20:18 -0000 1.9
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml 28 Oct 2003 22:07:41 -0000 1.10
@@ -4,113 +4,28 @@
%myvars;
]>
-
- Install Linux and supporting software
+
+ Install Unix-like system and supporting software
by Joel Aufrecht
-
- Paths and Users
-
-
- Assumptions in this section
-
-
-
-
- Fully qualified domain name of your server
- yourserver.test
-
-
- name of administrative access account
- remadmin
-
-
- OpenACS service
-
- service0
-
-service0
-
-
- OpenACS service account
- service0
-
-
- OpenACS database name
- service0
-
-
- Root of OpenACS service file tree
- /web/service0
-
-
- Location of source code tarballs for new software
- /tmp
-
-
- The OpenACS tarball contains some files which
- are useful while setting up other software. Those
- files are located at:
- /tmp/&tarballpath;/packages/acs-core-docs/www/files
-
-
- Database backup directory
- /web/service0/database-backup
-
-
- Service config files
- /web/service0/etc
-
-
- Service log files
- /web/service0/log
-
-
- Compile directory
- /usr/local/src
-
-
- PostGreSQL directory
- /usr/local/pgsql
-
-
- AOLServer directory
- /usr/local/aolserver
-
-
-
-
-
-
-
- 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
- marked like this. The other
- values we recommend you leave unchanged unless you have a
- reason to change them.
-
-
-
- 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 this
- thread for discussion.
-
-
-
-
-
-
- Install Linux
- You will need a PC running linux with the following software installed:
+
+ a Unix-like system
+ You will need a computer running a unix-like system with the following software installed:
- libxml2
+ tdomtcl
- gmake and the compile and build environment.
+ 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)
+
+and optionally these programs, which are included in most distributions:
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml,v
diff -u -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml 14 Oct 2003 10:05:44 -0000 1.5
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml 28 Oct 2003 22:07:41 -0000 1.6
@@ -369,16 +369,8 @@
Install nspam
-
-nspam is documented in acs-authentication. This html
- version of acs-core-docs was compiled without
- acs-authentication. To view nspam installation instructions,
- install acs-authentication and read /docs/acs-authentication.
-
-
+ url="/doc/acs-authentication/ext-auth-install.html">
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml,v
diff -u -r1.11 -r1.12
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml 20 Aug 2003 16:20:18 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml 28 Oct 2003 22:07:41 -0000 1.12
@@ -4,131 +4,206 @@
%myvars;
]>
-
- Overview
-
-
- by Vinod Kurup
-
-
-
- Purpose of this document
-
-
- This document will describe how to install, configure, and
- maintain an installation of OpenACS &version; on a Unix-like
- system, including all supporting software. All examples
- in this chapter are part of the OpenACS &version;-P or
- OpenACS &version;-O Reference Platform, which use Red
- Hat 8.0. Differences between the Reference Platform
- and common alternate platforms (Red Hat 9, Debian) are noted where known.
-
-
-
-
- Requirements
-
- You will need a PC (or equivalent) with at least these minimum
- requirements:
-
-
- Pentium processor
- 128 MB RAM
- (much more if you want Oracle)
- 4 GB hard drive
-
- You will need all everthing marked REQUIRED in software.
+
+ Installation Overview
-
- If you want to serve pages to people outside of your machine, you'll
- need a network connection of some type.
-
+
+ by Vinod Kurup
+
-
- Running a reliable database-backed web server requires experience
- with the server's environment, in this case UNIX. UNIX is not always
- an intuitive environment and this guide cannot hope to explain every
- nuance. You should be comfortable with the following tasks before
- attempting an installation:
+
+ Basic Steps
+
+ The basic steps to getting OpenACS up and running are:
-
-
-
- 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.
-
-
+
+ Install an OS (Linux, FreeBSD, OpenBSD, , , ).
+
+
+ Install a database (Oracle or
+ PostgreSQL).
+
-
- 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.
+
+ Install the AOLserver webserver.
+
+
+ Create a unique database and system user.
+ Install the OpenACS tarball, start and AOLserver instance, and
+ use the OpenACS web pages to complete installation
+ ().
+
+
+
+
+ Binaries and other shortcuts
+
+
+ The patched version of AOLserver we use is not currently
+ available in a precompiled binary.
+
+
+
+ The packaged version of
+ PostGreSQL in Debian and Red Hat and FreeBSD ports works fine.
+
+
+ Jonathan Marsden has created RPMs (at
+ http://www.xc.org)
+ for OpenACS 4.5 but there are not yet any for version
+ &version;.
+
+
+ An experimental script automating OpenACS checkout
+ and installation is in the openacs cvs tree at
+ /etc/install.sh.
+
+
+
+
+
+
+ Requirements
+
+ You will need a PC (or equivalent) with at least these minimum
+ requirements:
-
-
+
+ Pentium processor
+ 128 MB RAM
+ (much more if you want Oracle)
+ 4 GB hard drive
+ A Unix-like operating system with tcl, tdom, and
+ a mail transport agent. ()
+
+
All of the software that you will need is free and open-source,
except for Oracle. You can obtain a free copy of Oracle for
development purposes. This is described in the section.
+ linkend="install-oracle-getit"/> section.
-
-
-
-
- Steps involved
-
- The basic steps to getting OpenACS up and running are:
-
-
-
- Install an OS
-
- Install a database (Oracle or
- PostgreSQL)
-
-
- Install a webserver (AOLServer)
-
-
- Copy the OpenACS files into place and start the OpenACS installer, which will configure a database instance.
-
-
-
-
-
- How to use this guide
-
-
- This is text you will see on
+
+ Compatibility Matrix
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ OpenACS Version
+ 3.2.5
+ 4.5
+ 4.6
+ 4.6.1
+ 4.6.2
+ 4.6.3
+ 5.0.0
+
+
+ AolServer
+ 3
+ Verified
+
+
+ 3.3+ad13
+ Verified
+
+
+ 3.3oacs1
+ Verified
+
+
+ 3.4.2
+ No
+
+
+ 3.4.2oacs1
+ Verified
+
+
+ 3.5.5
+ Verified
+
+
+ 4
+ Verified but not for production
+
+
+ PostGreSQL
+ 7.0
+ Verified
+
+
+ 7.2.x
+ Verified
+
+
+ 7.3.2 - 7.3.4
+ No
+ Verified
+
+
+ Oracle
+ 8.1.6
+ Verified
+
+
+ 8.1.7
+ Verified
+
+
+ 9i
+ No
+ Untested
+
+
+
+
+
+
+
+
+
+ How to use this guide
+
+
+ This is text you will see on
screen, such as a Button or link
in a radio button list or menu.
-
- This is text that you will type.
-
- This is text from a program or file which you may need to
+
+ This is text that you will type.
+
+ This is text from a program or file which you may need to
examine or edit:
- if {$database == "oracle"} {
+ if {$database == "oracle"} {
set db_password "mysitepassword"
}
-
-
- This is text that you will
+
+
+ This is text that you will
see and type in a command shell, including text you may have to
change. It is followed by a list of just the commands,
which you can copy and paste.
- [root@localhost root]# su - nsadmin
+ [root@localhost root]# su - nsadmin
[nsadmin@localhost aolserver]$ svc -d /service/server1
[nsadmin@localhost aolserver]$ dropdb server1
DROP DATABASE
@@ -138,12 +213,106 @@
svc -d /service/server1
dropdb server1
createdb server1
-
-
-
-
-
- What if I get stuck?
+
+
+
+
+ Paths and Users
+
+
+ Assumptions in this section
+
+
+
+
+ Fully qualified domain name of your server
+ yourserver.test
+
+
+ name of administrative access account
+ remadmin
+
+
+ OpenACS service
+
+ service0
+
+service0
+
+
+ OpenACS service account
+ service0
+
+
+ OpenACS database name
+ service0
+
+
+ Root of OpenACS service file tree
+ /var/lib/aolserver/service0
+
+
+ Location of source code tarballs for new software
+ /tmp
+
+
+ The OpenACS tarball contains some files which
+ are useful while setting up other software. Those
+ files are located at:
+ /tmp/&tarballpath;/packages/acs-core-docs/www/files
+
+
+ Database backup directory
+ /var/lib/aolserver/service0/database-backup
+
+
+ Service config files
+ /var/lib/aolserver/service0/etc
+
+
+ Service log files
+ /var/lib/aolserver/service0/log
+
+
+ Compile directory
+ /usr/local/src
+
+
+ PostGreSQL directory
+ /usr/local/pgsql
+
+
+ AOLServer directory
+ /usr/local/aolserver
+
+
+
+
+
+
+
+ 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
+ marked like this. The other
+ values we recommend you leave unchanged unless you have a
+ reason to change them.
+
+
+
+ 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 this
+ thread for discussion.
+
+
+
+
+
+
+
+ Getting Help during installation
We'll do our best to assure that following our instructions will get
@@ -153,7 +322,7 @@
-
+
Keep track of the commands you are run and record their output. I
like to do my installations in a shell inside of emacs
(M-x shell) so that I can save
@@ -163,7 +332,7 @@
-
+
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
@@ -174,31 +343,31 @@
-
+
Search the bboards at
openacs.org - you'll often find many people who have
struggled through the same spot that you're in.
-
+
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.
-
+
Ask questions at the irc channel on openprojects.net
(#openacs). They're knowledgeable and quite friendly
if you can keep them on topic.
-
+
Post a question on the bboards. Make sure
you've done a search first. When you do post, be sure to include
@@ -210,268 +379,16 @@
-
+
If you find errors in this document or if you have ideas about
making it better, please post them in our
BugTracker.
-
-
-
+
+
+
+
+ ($Id$)
-
- Is there an easier way?
-
-
- After reading through this tome, you may ask yourself if there is a
- better way. Well, not quite. Jonathan Marsden has created RPMs (at
- http://www.xc.org)
- for OpenACS 4.5 but there are not yet any for version
- &version;. There has been talk about automating the install process,
- but that hasn't happened yet. Stay tuned!
-
-
-
-
-
- Where did this document come from?
-
- This document was created by Vinod Kurup, but it's really
- just plagiarism from a number of documents that came before it. If
- I've used something that you've written without proper credit, let me
- know and I'll fix it right away.
-
- Versions 4.6.2 to present were edited by Joel Aufrecht.
-
-
- These are a few of my sources:
-
-
- ArsDigita installation guide
-
-
-
- OpenACS 3.x installation guide
-
-
-
- Gilbert Wong's FreeBSD
- installation guide
-
-
-
- Vinod Kurup's Brief OpenACS4
- installation guide
-
-
-
- Joel
- Aufrecht's OpenACS 4.5 Quick Guide.
-
-
-
-
- Please also see the section for more acknowledgements.
-
-
-
-
- Linux Install Guides
-
- Here's a list of some helpful documentation for various OS's
-
-
-
-
- Painless Debian
- GNU/Linux by Stephen van Egmond
-
-
-
-
- Official
- Debian Guide
-
-
-
-
-
- RedHat
-
-
-
-
-
- Mandrake
-
-
-
-
-
- SuSE
-
-
-
-
-
-
-
-
- Security Information
-
- Once you get your OS installed, it's imperative that you secure your
- installation. As Jon Griffin repeatedly warns us, "No distribution is
- secure out of the box." The Reference Platform implements
- some basic precautions, but security is a process, not a
- condition. If you are responsible for a computer hooked to the
- internet, you are responsible for learning some rudiments of
- security, such as monitoring the state of a computer,
- maintaining patch levels, and keeping backups. We recommend
- these resources:
-
-
-
-
-
- Securing and Optimizing Linux - version 2.0
-
-
-
- Jon
- Griffin's notes
-
-
- Linux Administrators
- Security Guide
-
-
- Installation
- of a Secure Webserver
-
-
-
- Bruce
- Schneier's Crypto-Gram, especially The
- security patch treadmill and Monitoring First.
-
-
-
-
-
-
- Resources
-
-
- Here are some resources that OpenACS users have found useful.
-
-
-
- Books
-
-
-
-
- Philip
- and Alex's Guide to Web Publishing - A very readable
- guide to database-backed community websites.
-
-
-
-
-
- UNIX
- Power Tools - An excellent introduction to the
- command line tools and basic programs of UNIX
-
-
-
-
-
- UNIX
- System Administration Handbook (formerly the "red book"
- - now the "purple" book)
-
-
-
-
-
- UNIX
- System Administrator's Bible - (LePage and Iarerra 1998;
- IDG)
-
-
-
-
-
- Running
- Linux
-
- Learning
- Gnu Emacs
-
-
-
- Linux
- in a Nutshell
-
-
-
-
-
-
-
- Web Sites
-
-
-
-
- The UNIX
- Reference Desk
-
-
-
-
-
- The Linux Documentation
- Project
-
-
-
-
-
- LPI
- certification exam preps - A series of articles from
- IBM developerworks on basic and intermediate Linux skills
- (requires registration)
-
-
-
-
-
-
-
-
- ($Id$)
-
-
+
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/quick.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/quick.xml,v
diff -u -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/quick.xml 20 Aug 2003 16:20:19 -0000 1.2
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/quick.xml 28 Oct 2003 22:07:41 -0000 1.3
@@ -4,52 +4,47 @@
%myvars;
]>
-
- Quick Install
+
+ Quick Install
+
+
+ by Joel Aufrecht
+
-
- by Joel Aufrecht
-
-
-
- Purpose of this document
-
+
+ Purpose of this document
+
This page describes a minimal installation of OpenACS with
PostGreSQL (not Oracle). It will produce a working OpenACS
installation in under an hour. It excludes source control,
full text search, ssl, managed services (daemontools),
DocBook, and qmail.
-
-
- For Red Hat 9
-
-
- Install PostGreSQL 7.3.2 from RPM. Select
+
+
+ For Red Hat 9
+ Install PostGreSQL 7.3.2 from RPM. Select
Menu > System Settings > Add/Remove
Applications and select Database Server.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- After completing installation and restarting the server, go to for configuration and customization instructions. You can upgrade a Quick Install with source control, full text search, backup/recovery, and other production features by walking through the Installation documentation and doing the steps marked OPTIONAL.
-
- ($Id$)
-
-
+
+Postgres section missing
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ After completing installation and restarting the server, go to for configuration and customization instructions. You can upgrade a Quick Install with source control, full text search, backup/recovery, and other production features by walking through the Installation documentation and doing the steps marked OPTIONAL.
+
+ ($Id$)
+
+
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/red-hat.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/red-hat.xml,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/red-hat.xml 20 Aug 2003 16:20:19 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/red-hat.xml 28 Oct 2003 22:07:41 -0000 1.4
@@ -19,6 +19,34 @@
to install a new machine from scratch compared to installing each
of these packages installed independently.)
+ The installation guide assumes 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
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/software.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/software.xml,v
diff -u -r1.6 -r1.7
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/software.xml 14 Oct 2003 10:05:44 -0000 1.6
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/software.xml 28 Oct 2003 22:07:41 -0000 1.7
@@ -17,105 +17,6 @@
Transport Agent and source control system, are also needed for
a fully effective instance.
-
-
- Compatibility Matrix
-
- by Joel Aufrecht
-
-
- Compatibility Matrix
-
-
-
-
-
-
-
-
-
-
-
-
-
- OpenACS Version
- 3.2.5
- 4.5
- 4.6
- 4.6.1
- 4.6.2
- 4.6.3
-
-
- AolServer
- 3
- Verified
-
-
- 3.3+ad13
- Verified
-
-
- 3.3oacs1
- Verified
-
-
- PostGreSQL
- 7.0
- Verified
-
-
- 7.2.x
- Verified
-
-
- 7.3.2
- Not compatible
- Untested
-
-
- Oracle
- 8.1.6
- Verified
-
-
- 8.1.7
- Verified
-
-
- 9i
- No
-
-
-
-
-
-
-
Individual Programs
@@ -140,7 +41,7 @@
Linux
- . The installation assumes a linux kernel of 2.2.22 or newer, or 2.4.14 or newer.
+ The installation assumes a linux kernel of 2.2.22 or newer, or 2.4.14 or newer.
Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/win2kinstall.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/win2kinstall.xml,v
diff -u -r1.7 -r1.8
--- openacs-4/packages/acs-core-docs/www/xml/install-guide/win2kinstall.xml 20 Aug 2003 16:20:19 -0000 1.7
+++ openacs-4/packages/acs-core-docs/www/xml/install-guide/win2kinstall.xml 28 Oct 2003 22:07:41 -0000 1.8
@@ -4,7 +4,7 @@
%myvars;
]>
-
+OpenACS Installation Guide for Windows2000
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/ext-auth-design.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/ext-auth-design.xml,v
diff -u -r1.1 -r1.2
--- openacs-4/packages/acs-core-docs/www/xml/kernel/ext-auth-design.xml 21 Aug 2003 08:04:31 -0000 1.1
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/ext-auth-design.xml 28 Oct 2003 22:07:41 -0000 1.2
@@ -5,7 +5,7 @@
%myvars;
]>
-
+External Authentication Design
