Weblog

Introduction to OpenACS

Created by Rocael Hernández Rizzardini, last modified by Gustaf Neumann 22 Mar 2019, at 11:04 PM

Start Playing With Openacs. 

Before you know it, you will Become an Expert in the basics!

This is a quick guide of the things that you have to know in order to become productive in OpenACS. You have to master certain things before you can advance. A developer has to become an expert in handling and knowing the tools that he uses.

MAYBE, the very first thing to become aware of, is that your installed OpenACS server is self-documenting. Take a look at http://your.server/doc/ and spend some time here; I'd suggest an hour or so just to view the structure and get familiar with what is said where, and how it is said. WHENEVER you ask a question and get an answer, try to seek out the solution you get in the docs and piece it together. This WILL help you to gradually become an expert.

You have to become expert in:
- Emacs
- Tcl
- Linux (for OpenACS installation)
- Searching on OpenACS
- Functions that provides NaviServer
- Use of OpenACS
- Basic API OpenACS

Emacs:
You have to become expert in the text editor that you use for development since is a fundamental piece in your development environment. Not knowing the text editor in used makes it very limited and your work will be very unproductive.


Emacs is an extendable editor (but you can use any editor you want).  Check out the oacs emacs module, pretty cool! en:ide-emacs

Minimal knowledge of Emacs:
 - window management
 - copy/paste
 - DB access from emacs
     - It's actually very simple, you run a shell in emacs and then run the text db client in the shell in emacs. Once inside emacs, <code>M-x shell (enter)</code> will put you in a shell. From there, you can do anything the shell can do, and then if you want you can save everything. So, oracle users can use sqlplus, postgres users can use psql. (watch out... by default emacs will NOT offer to save the buffer before you exit!)
 - file management 
 - searching

Required time to know emacs ( 4 hours aprox).

PLEASE DON'T LET THAT SCARE YOU... you don't actually need to know EVERYTHING about emacs or be an expert in emacs itself. Me, I just know how to move the cursor, type, define a macro (no, really, this is easy too) and get into shell mode. Oh, and I can run (doctor) in the *scratch* buffer.

Tcl

Try searching google for "Tcl for Web Nerds" and/or look for some good, basic tutorials. I think you can learn at your own pace, and still have fun with OpenACS.

Minimal knowledge of Tcl:
- lists and manipulation functions
- strings
- proc/namespaces
- switch
- regular expressions (regexp)
- Everything that is basic to Tcl

 (jiml) I'll suggest you find out how to run tclsh (or, say, psql) from inside emacs (see comment about emacs shell mode, above on this same page).


Required time to know and become used to Tcl (6-12 hours approx).

TCL for web nerds: https://openacs.org/test-doc/tcl-wn

Linux (for OpenACS Installation)

Minimal Knowledge
- user management
- group management
- permission
- compilation
- searching
- environment variables

Searching in OpenACS

Do your searching in OpenACS in different areas:
- forums (use google, example: site:opeancs.org postgres 8.1)
- code (use grep and find):  find /path/name -name "*-oracle.xql" -exec grep whatever {} \; -print
- API doc (use to search procs)

Required Time (4 hours approx)

Debugging in OpenACS

This will help us to identify exactly what is producing an error. For that you have to learn::
- To read the log
- To use the Developer Support

To log everything in your log file, go to config.tcl and set "debug true.

Required Time (4 hours)

Functions of NaviServer

Check all of them ( ns_*)

HOWEVER NOTE that it is MUCH more important to see how these calls are used in OpenACS! (aside from which, it will take you less time to understand a single OpenACS interaction if you just look at one... the notes tutorial has a few; I would suggest that you do that tutorial and actually type everything in rather than cut and paste... then you touch every word)

NaviServer Documentation:
https://naviserver.sourceforge.io/n/toc.html

Required Time (4 hours aprox)

Use of OpenACS

Become expert in using OpenACS as a tool, from the user interface point of view.

Important items:
- Developer administration (Site-Wide-Admin) (4 hours)
- Applications: (4 hours or more)
    - User administration:
        - Understand the roles that exist.
            - Will help a lot if you understand more about .LRN
- Basic API of OpenACS

    - The -most- basic part of openacs is its object system.
       Start to get familiar with the object system by reading
       the definition which starts "create table acs_objects"
       and find out everything you can about how to define your
       own object types, how inheritance works, how to drop your types.
       REMEMBER to drop things in -reverse- order from how you create.
       Learn how acs_object inheritance works.
    - Object and User and permission management
    - DB (a detailed document describing the database access api is on your installed server at http://your.server/doc/db-api.html | a search for all tcl db procs: db_*)
    - ad_conn (provides basic information regarding the browser the request is coming from as well as the user (if any logged in) who is doing the browsing; search at http://your.server/api-doc)
    - Permissions: a permission is a statement of the following form:
         PARTY (from table parties) whose party_id is X has
         PRIVILEGE (from table acs_privileges) whose textual name is Y on
         OBJECT (from table acs_objects) whose object_id is Z

         You can:

             - make such a statement (ex. group-of-my-students has "read" on my-student-forums)

             - ask (in various ways) whether such a statement has been made

         I would suggest for further study, that you:

             - MOST IMPORTANT: try things out!!

             - search google for "permissions tediously explained"

             - also see the "notes" tutorial
 

    - acs_rel is good tool for connecting objects. One application: groups of users (so one acs_rel "connects" one user to a common object, representing the group, ex: if andy, betty, carl, dirk and ed are in groups alpha-beta, there will be five acs_rels, all of them tied to alpha-beta on one side of the rel, and for rel, that rel will have one of the users on the other side of the rel)
    - Site-map (instances and site nodes)

    - another VERY important part of OpenACS that was not listed here before, is the templating system. If you have OpenACS installed, you can view the docs at http://your.server/doc/acs-templating/ and you can see dozens of demonstrations at http://your.server/doc/acs-templating/demo AAANNND if that's not enough, every demo has sample code and you can plug it right in to your page! As you can see, you can show values of Tcl variables, make lists and forms, include other templates and show database results and do all of this and more, looking any way you want.

 

Testing with Selenium

Created by Hamilton Chua, last modified by Gustaf Neumann 22 Mar 2019, at 10:13 PM

Testing with Selenium

Selenium is primarily for feature testing, user interface and acceptance testing.

Recently OpenACS got support for Selenium RC on CVS HEAD to be released in OpenACS 5.6 sometime in the future.

Forum Posts :

https://openacs.org/forums/message-view?message_id=365992

Command Reference :

Selenium Documentation

Interesting Articles :

• http://wiki.rubyonrails.com/rails/pages/SeleniumIntegration
• http://www-128.ibm.com/developerworks/web/library/wa-selenium-ajax/

Tools :

Selenium Recorder Firefox Extension

• http://www.openqa.org/selenium-ide/

Quickstart to Writing Tests:

  This quickstart shows you how to start writing selenium tests with selenium and the selenium recorder (aka selenium-ide).

1. You need to have the Firefox Browser version 1.5 or higher
2. Proceed to http://www.openqa.org/selenium-ide/ and click on the link (Firefox Extension) to install the Selenium IDE firefox extension
3. Restart firefox
4. Click Tools -> Selenium IDE
5. The selenium ide window will open
6. It will start recording your actions in the browser.
7. You can go ahead and go to a url and click on the links to see how the recorder records your actions.
8. To disable recording while the recorder window is open, click the "red" button.
9. Selenium verifies that a test or action is successful by checking the title or text in a webpage
10. You can verify the title of the current page  by right clicking on the webpage you are currently in and click Append Selenium -> verifyTitle
11. You can verify the presence of text in a page by highlighting some text and then right click -> Append Selenium Command -> verifyTextPresent

Click here for a video of how to use Selenium IDE.

Selenium IDE allows you to create, save, load and run tests right from firefox without having to install Selenium on the server.

Selenium on the Server

Aside from using the Selenium IDE to test webpages, selenium itself can be installed on the server. This provides a central location for testers and developers to view and execute tests. "Server" here refers to the OpenACS instance where your application is running. If your OpenACS instance is in http://your_openacs_instance, then selenium should be installed in http://your_openacs_instance/selenium

WARNING: We do not recommend installing selenium on the server of a production instance. Only install selenium on a staging or test server. This is because

• When tests fail, they leave a mess of test data that you will not want on production
• Selenium is mostly javascript that can run on any browser. While there are currently no reports of exploits on servers running selenium, we do not want and (you should not too) take the risk of having it on a production box where it is possible for a clever hacker to utilize a browser vulnerability to break into your server.

To instal selenium on the server :

1. Download selenium from http://www.openqa.org/selenium-core/download.action
2. Choose to download the "Full Release"
3. After downloading, decompress the file.
4. You will see a folder selenium-x.x where "x.x" is the version of selenium you downloaded.
5. Go inside this folder and look for the "selenium" folder.
6. Copy this "selenium" folder to the openacsroot/www/ directory
7. Launch a browser and go to http://your_openacs_instance/selenium

At this point, selenium is installed. The page that you see when you visit /selenium is the default selenium page. It lists the tests that come with selenium.

To start using selenium on the server :

1. Customize the landing page /selenium/index.html
2. Create Test Suites for each package. A test suite is just a file in selenium/tests that lists a number of tests for a particular feature or section of an application. For instance, TestSuite-News.html would be a file that lists the tests for the News Package.
3. Upload tests to the /selenium/tests folder.

Guidelines for Creating and Running Tests for OpenACS Packages

Coming Soon .....

Some Limitations :

• Minor Issue with SSL  : Selenium can't switch properly between http and https pages.
• File Input type not supported : You can't tell selenium to upload a file. But there is a work around with firefox. Read it here
• WYSIWYG Editors  : Selenium can't write to some WYSIWYG editors like htmlarea but it seems to work with xinha, you just need to get the textearea element name that xinha uses.

Tips :

Use xpath to find specific html elements

I have  scenario where I want to click ona image field with no id or name attribute so there's no easy way to tell selenium to click it. We can either ask the designer to put an id or name attribute or use xpath. Let's say the image button in question looks like this

 <input type="image" src="images/long-login-btn.gif" width=166 height=15 />

the xpath syntax will be

 //input[@src='https://openacs.org/images/long-login-btn.gif']

and you can use this in conjunction with clickAndWait

Use javascript to create dummy values

You can use javascript to generate values like so

  javascript{'test' + (new Date()).getTime()}

and use store to store them to a value for use later in the selenium script.

 

JSON

Created by Michael Aram, last modified by Michael Aram 20 Mar 2019, at 05:17 PM

Caveat: Page under construction

There are several libraries and ways available to parse and/or generate JSON in OpenACS. 

• rl_json
• yajl-tcl
• tdom > 0.9

yajl-tcl

Created by Michael Aram, last modified by Michael Aram 20 Mar 2019, at 05:16 PM

Caveat: Page under construction

yajl-tcl

Example Installation for NaviServer under Ubuntu 

apt-get install libyajl-dev pkg-config
cd /var/tmp
export YAJLTCL_VERSION=1.7.0-rc1
wget --no-check-certificate -O yajl-tcl-${YAJLTCL_VERSION}.tar.gz https://github.com/flightaware/yajl-tcl/archive/v${YAJLTCL_VERSION}.tar.gz
cd /usr/local/src
tar -xzf /var/tmp/yajl-tcl-${YAJLTCL_VERSION}.tar.gz
cd yajl-tcl-${YAJLTCL_VERSION}
autoconf
./configure --enable-threads --with-tcl=/usr/local/ns/lib
make
make install

Aliases at CVS

Created by Rocael Hernández Rizzardini, last modified by Gustaf Neumann 13 Feb 2019, at 11:48 PM

Useful aliases for cvs.openacs.org:

• acs-core *
• dotlrn-all *
• dotlrn-extras *
• contrib
• project-manager-all
• xotcl-all
• dotngo
• dotwrk

 * These aliases are controlled by OCT and .LRN honchos groups, the packages that belong to these aliases are the ones that are maintained by both groups. They are not to be changed unless approved by OCT and / or .LRN technical committee.

Below the packages details for each alias:

##################################################################
# OpenACS Core
##################################################################

acs-core -a openacs-4/packages/acs-admin
openacs-4/packages/acs-api-browser
openacs-4/packages/acs-authentication
openacs-4/packages/acs-automated-testing
openacs-4/packages/acs-bootstrap-installer
openacs-4/packages/acs-content-repository
openacs-4/packages/acs-core-docs
openacs-4/packages/acs-developer-support
openacs-4/packages/acs-kernel
openacs-4/packages/acs-lang
openacs-4/packages/acs-mail-lite
openacs-4/packages/acs-messaging
openacs-4/packages/acs-reference
openacs-4/packages/acs-service-contract
openacs-4/packages/acs-subsite
openacs-4/packages/acs-tcl
openacs-4/packages/acs-templating
openacs-4/packages/ref-countries
openacs-4/packages/ref-language
openacs-4/packages/ref-timezones
openacs-4/packages/acs-translations
openacs-4/packages/intermedia-driver
openacs-4/packages/openacs-default-theme
openacs-4/packages/notifications
openacs-4/packages/search
openacs-4/packages/tsearch2-driver
openacs-4/ChangeLog
openacs-4/license.txt
openacs-4/readme.txt
openacs-4/bin
openacs-4/content-repository-content-files
openacs-4/database-backup
openacs-4/etc
openacs-4/log
openacs-4/tcl
openacs-4/www

##################################################################
# .LRN aliases
##################################################################

dotlrn-all -a acs-datetime acs-events
attachments bulk-mail calendar faq file-storage
forums general-comments news lars-blogger
weblogger-portlet rss-support trackback oacs-dav
xml-rpc categories dotlrn dotlrn-syllabus new-portal
profile-provider user-profile bm-portlet dotlrn-bm
calendar-portlet dotlrn-calendar dotlrn-portlet
dotlrn-dotlrn faq-portlet dotlrn-faq forums-portlet
dotlrn-forums fs-portlet dotlrn-fs news-portlet
dotlrn-news static-portlet dotlrn-static
dotlrn-homework dotlrn-weblogger evaluation
evaluation-portlet dotlrn-evaluation assessment
assessment-portlet dotlrn-assessment theme-selva
theme-zen dotlrn-random-photo random-photo-portlet
views

dotlrn-extras -a lors lorsm lorsm-portlet dotlrn-lorsm
photo-album photo-album-portlet dotlrn-photo-album
survey-portlet dotlrn-survey survey chat
dotlrn-chat chat-portlet xotcl-core imsld
imsld-portlet dotlrn-imsld

##################################################################
# Project Manager aliases
##################################################################

project-manager-all -a calendar acs-events acs-datetime
acs-mail-lite categories logger
project-manager general-comments
organizations


##################################################################
# xoTCL Stuff + required
##################################################################

xotcl-all -a xotcl-core xotcl-request-monitor xowiki categories
acs-events acs-datetime file-storage oacs-dav
rss-support general-comments

 

 

 

 

Reference Data - Country

Created by Torben Brosten, last modified by Gustaf Neumann 13 Feb 2019, at 11:43 PM

Package Specification Summary for Package: ref-countries

Summary:	ISO 3166 country data.
Description:	Countries supplies the ISO 3166 Country data for acs-reference.
Documentation:	Package Documentation
Maturity:	Immature
This package depends on:	acs-kernel acs-reference
Packages that depend on ref-countries:	accounts-ledger acs-lang ams contacts ecommerce postal-address ref-currency value-based-shipping
Package parameters:	None

Bug Tracker Summary for Package: ref-countries

There is no package with the name "ref-countries" known to bug-tracker.

Code Metrics Summary for Package: ref-countries

# Tcl Procs	2
# Tcl Lines	110
# Tcl Blank Lines	20
# Tcl Comment Lines	11
# Automated Tests	1
# Stored Procedures	PG: 0 ORA: 0
# SQL Lines	PG: 44 (blank 8 comments 11) ORA: 49 (blank 7 comments 11)
# ADP pages	0
# ADP lines	0
# Include pages (ref-countries/lib/)	0
# Documentation pages	1 (Package Documentation)
# Documentation lines	16
Browse Source	API-browser
Github Repository:	https://github.com/openacs/openacs-core

 

Reference Data - Language

Created by Robert Taylor, last modified by Gustaf Neumann 13 Feb 2019, at 11:41 PM

Package Specification Summary for Package: ref-language

Summary:	ISO 639-1 language reference data for acs-reference.
Description:	This is the ISO 639-1 language reference data (with languages names in English).
Maturity:	Mature
This package depends on:	acs-kernel acs-reference
Packages that depend on ref-language:	accounts-ledger acs-lang ecommerce ref-currency
Package parameters:	None

Bug Tracker Summary for Package: ref-language

There is no package with the name "ref-language" known to bug-tracker.

Code Metrics Summary for Package: ref-language

# Tcl Procs	6
# Tcl Lines	267
# Tcl Blank Lines	47
# Tcl Comment Lines	14
# Automated Tests	1
# Stored Procedures	PG: 0 ORA: 0
# SQL Lines	PG: 49 (blank 10 comments 9) ORA: 54 (blank 10 comments 9)
# ADP pages	0
# ADP lines	0
# Include pages (ref-language/lib/)	0
# Documentation pages	0
# Documentation lines	0
Browse Source	API-browser
Github Repository:	https://github.com/openacs/openacs-core

 

OpenACS Translation server

Created by Gustaf Neumann, last modified by Gustaf Neumann 16 Dec 2018, at 09:45 PM

The OpenACS translation server is currently not supported. Volunteers are welcome to help to revive this project  which helps to collect message keys in various languages from users and to feed this into the OpenACS core distributions.

On interest, please send a mail to oct@openacs.org.

ACS Mail Lite

Created by Nick Carroll, last modified by Gustaf Neumann 01 Dec 2018, at 10:31 AM

Package Specification Summary for Package: acs-mail-lite

Summary:	Simplified reliable email transmission with bounce management.
Description:	This package provides a service for sending and receiving messages, messages are queued in the database to ensure reliable sending and make sending a message 'transactional'. Replacement for acs-mail.
Documentation:	Package Documentation
Maturity:	Mature and Standard
This package depends on:	acs-kernel acs-service-contract acs-tcl
Packages that depend on acs-mail-lite:	acs-admin acs-authentication acs-messaging acs-subsite bulk-mail contacts dotlrn forums mail-tracking notifications postcard project-manager simulation
Package parameters:	IMAP: IMAPHost IMAP Host to be used for sending emails (default localhost, type string, scope instance) IMAP: IMAPPassword IMAP Password to be used for sending emails (default , type string, scope instance) IMAP: IMAPPort IMAP Port to be used for sending emails (default 25, type number, scope instance) IMAP: IMAPTimeout IMAP Timeout. Waiting time until we give up with the mailserver. (default 60, type number, scope instance) IMAP: IMAPUser IMAP User to be used for sending emails (default , type string, scope instance) SMTP: SMTPHost SMTP Host to be used for sending emails (default localhost, type string, scope instance) SMTP: SMTPPassword SMTP Password to be used for sending emails (default , type string, scope instance) SMTP: SMTPPort SMTP Port to be used for sending emails (default 25, type number, scope instance) SMTP: SMTPTimeout SMTP Timeout. Waiting time until we give up with the mailserver. (default 60, type number, scope instance) SMTP: SMTPUser SMTP User to be used for sending emails (default , type string, scope instance) email: BounceDomain Email Domain for outgoing messages (default , type string, scope instance) email: BounceMailDir Location of the maildir location that accepts incoming bounces (default , type string, scope instance) email: BounceScanQueue How often (in seconds) to scan for new bounces (default 120, type number, scope instance) email: EnvelopePrefix The prefix for sending mail that will be handled by this instance. Use alphanumeric characters only. (default bounce, type string, scope instance) email: FilesystemAttachmentsRoot Path of a folder in the filesystem into which files are allowed to be read and sent as attachments. Trying to send attachments residing outside this folder will throw an error. Set this parameter to the root of your filesystem will disable this restriction. Default for the empty value of this parameter will be to allow only files into the temporary folder of the system, as in '[ns_tmpdir]' (default , type string, scope instance) email: FixedFont Font definition (after the font tag) that will always be wrapped around HTML e-mail. Example: face=Verdana size=2. Default is empty (default , type string, scope instance) email: FixedSenderEmail Email address that will be always the email stored in the sender. Default is empty (default , type string, scope instance) email: FolderID Folder ID of a folder in the content repository that contains files that can be included using checkboxes in each e-mail send out of the system. This effects /lib/email (default , type number, scope instance) email: MMEncodeBin Location of mmencode executable. (default /usr/bin/mmencode, type string, scope instance) email: MaxBounceCount Number of bounced emails after resulting in disabling an email-address (default 10, type number, scope instance) email: MaxDaysToBounce Number of days after mail sending a bounce is expected at the very latest (default 2, type number, scope instance) email: MaxNotificationCount Number of times the user will get a notification that his email got disabled in the system (default 4, type number, scope instance) email: NotificationInterval Number of days the users with bouncing email will be notified again on how to re-enable the email again (default 7, type number, scope instance) email: NotificationSender Sender of the notification email (default , type string, scope instance) email: OriginatorEmail Answers question: What value gets assigned to Originator header? Choices are: fixed_sender, from_address, message_id, reply_to, or bounce_address (value returned from acs_mail_lite::bounce_address). Originator defined in rfc2822 section 3.6.2 (default bounce_address, type string, scope instance) email: send_immediately Boolean value to say whether new mails should be send out immediately or stored in the db before send out. (default 0, type number, scope instance) inbound_email: IncomingDomain Email Domain for incoming messages (default , type string, scope instance) inbound_email: IncomingFilterProcName Procedure name for custom filtering of incoming email. Default is empty string. (default , type string, scope instance) inbound_email: IncomingMailDir Location of the maildir location that accepts incoming bounces (default , type string, scope instance) inbound_email: IncomingMaxAge Maximum time to accept replies from sent email before expiring. 604800 is 1 week of (seconds). 0 = does not expire (default 604800, type number, scope instance) inbound_email: IncomingMode Incoming email mode. Choices are: legacy (same behavior up to OpenACS 5.9.1. Deprecated, will be removed in future versions), maildir (use a MailDir location for incoming email), imap (use IMAP for incoming email). (default maildir, type string, scope instance) inbound_email: IncomingScanRate Duration between scans for new email (seconds) (default 120, type number, scope instance) rollout_support: EmailAllow Tcl list of email addresses that are allowed to receive messages when delivery mode is set to filter (default , type string, scope instance) rollout_support: EmailDeliveryMode Set how message will be delivered. default: Email messages are sent via the tcllib smtpd implementation. nssmtpd: try to send mail via SMTP based on the NaviServer nssmtpd module. log: Email messages are written to the server's error log. ignore: just write a single line per ignored mail delivery attempt. redirect: Email messages are redirected to the addresses specified by the EmailRedirectTo parameter. If this list is absent or empty, email messages are written to the server's error log. filter: Email messages are sent via SMTP if the recipient appears in the EmailAllow parameter, otherwise they are logged. The setting 'filter' and 'redirect' can be combined with 'nssmtpd' as in 'filter nssmtpd' to specify the delivery implementation (default default, type string, scope instance) rollout_support: EmailRedirectTo Tcl list of email addresses to redirect to (default , type string, scope instance)

Bug Tracker Summary for Package: acs-mail-lite

Open Bugs:	4
All Tracked Issues:	30
Latest Bug Opened:	2019-06-19 Mail server down — no retry?
Latest Bug Fixed:	2021-08-27 redirect does not work in acs-mail-lite 5.10.0d12.
Top Bug Submitters:	Jade Rubick (4) Benjamin Brink (3) Martin Magerl (2) Dirk Gomez (1) Brian Fenton (1)
Top Bug Fixers:	Malte Sussdorff (7) Gustaf Neumann (6) Jade Rubick (3) Dave Bauer (2) Caroline Meeks (1) Rocael Hernández Rizzardini (1) Torben Brosten (1)

Code Metrics Summary for Package: acs-mail-lite

# Tcl Procs	67
# Tcl Lines	5800
# Tcl Blank Lines	765
# Tcl Comment Lines	948
# Automated Tests	2
# Stored Procedures	PG: 0 ORA: 0
# SQL Lines	PG: 433 (blank 48 comments 216) ORA: 423 (blank 39 comments 213)
# ADP pages	1
# ADP lines	14
# Include pages (acs-mail-lite/lib/)	0
# Documentation pages	55 (Package Documentation)
# Documentation lines	2572
Browse Source	API-browser
Github Repository:	https://github.com/openacs/openacs-core

 

Commands for ds/shell to test, whether you mail setup is correct:

set to_addr [party::get -party_id [ad_conn user_id] -element email]
set from_addr [parameter::get -parameter HostAdministrator -package_id $::acs::kernel_id]

acs_mail_lite::send_immediately -to_addr $to_addr -from_addr $from_addr -body "hi" -subject "testing with send_immediately"

AOLserver administration

Created by OpenACS community, last modified by Gustaf Neumann 06 Jul 2018, at 10:41 AM

This page is mostly outdated and we keep it for a reference. For non-packaged installs on *nix systems, consider naviserver-openacs which supports systemd and upstart scripts.

Automating AOLserver startup and stop

The simplest way to start and stop and OpenACS site is to run the startup shell script provided in the OpenACS distribution, /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run. This runs as a regular task, and logs to the logfile. To stop the site, kill the script.

A more stable way to run OpenACS is with a "keepalive" mechanism of some sort, so that whenever the server halts or is stopped for a reset, it restarts automatically. This is recommended for development and production servers.

The Reference Platform uses Daemontools to control AOLserver. An alternative method, is using inittab.

Configuring Daemontools

1. Daemontools must already be installed. If not, install it.

2. Each service controlled by daemontools must have a directory in /service. That directory must have a file called run. It works like this:

   • The init program starts every time the computer is booted.

   • A line in init's configuration file, /etc/inittab, tells init to run, and to restart if necessary, svscanboot.

   • svscanboot checks the directory /service every few seconds.

   • If it sees a subdirectory there, it looks for a file in the subdirectory called run. If it finds a run file, it creates a supervise process

   • supervise executes the run script. Whenever the run script stops, supervise executes it again. It also creates additional control files in the same directory.

   Hence, the AOLserver instance for your development server is started by the file /service/$OPENACS_SERVICE_NAME/run. But we use a symlink to make it easier to add and remove stuff from the /service, so the actual location is /var/lib/aolserver/$OPENACS_SERVICE_NAMEetc/daemontools/run.

   Daemontools creates additional files and directories to track status and log. A daemontools directory is included in the OpenACS tarball at /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools. To use it, first kill any existing AOLserver instances. As root, link the daemontools directory into the /service directory. Daemontools' svscan process checks this directory every five seconds, and will quickly execute run.

   [$OPENACS_SERVICE_NAME etc]$ killall nsd
   nsd: no process killed
   [$OPENACS_SERVICE_NAME etc]$ emacs /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run
   [$OPENACS_SERVICE_NAME etc]$ exit
   
   [root root]# ln -s /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run /service/$OPENACS_SERVICE_NAME/run

   Verify that AOLserver is running.

   [root root]# ps -auxw | grep nsd
   $OPENACS_SERVICE_NAME   5562 14.2  6.2 22436 15952 ?       S    11:55   0:04 /usr/local/aolserver/bin/nsd -it /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl -u serve
   root      5582  0.0  0.2  3276  628 pts/0    S    11:55   0:00 grep nsd
   [root root]#

3. The user $OPENACS_SERVICE_NAME can now control the service $OPENACS_SERVICE_NAME with these commands:

   • svc -d /service/$OPENACS_SERVICE_NAME - Bring the server down

   • svc -u /service/$OPENACS_SERVICE_NAME - Start the server up and leave it in keepalive mode.

   • svc -o /service/$OPENACS_SERVICE_NAME - Start the server up once. Do not restart it if it stops.

   • svc -t /service/$OPENACS_SERVICE_NAME - Stop and immediately restart the server.

   • svc -k /service/$OPENACS_SERVICE_NAME - Sends the server a KILL signal. This is like KILL -9. AOLserver exits immediately. If svc -t fails to fully kill AOLserver, use this option. This does not take the server out of keepalive mode, so it should still bounce back up immediately.

4. Install a script to automate the stopping and starting of AOLserver services via daemontools. You can then restart a service via restart-aolserver $OPENACS_SERVICE_NAME

   [root root]# cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver
   [root root]# chmod 755 /usr/local/bin/restart-aolserver
   [root root]#

5. At this point, these commands will work only for the root user. Grant permission for the web group to use svc commands on the $OPENACS_SERVICE_NAME server.

   [root root]# /usr/local/bin/svgroup web /service/$OPENACS_SERVICE_NAME
   [root root]#

6. Verify that the controls work. You may want to tail -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log in another window, so you can see what happens when you type these commands.

   Most of this information comes from Tom Jackson's AOLserver+Daemontools Mini-HOWTO.

Table 6.1. How it Works

Program	Invoked by this program ...	... using this file	Where to find errors	Log goes to	Use these commands to control it
svscanboot	init	/etc/inittab	ps -auxw | grep readproctitle	n/a
aolserver	supervise (a child of svscanboot)	/service/$OPENACS_SERVICE_NAME/run	/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/error.log	/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME.log	svc -k /service/$OPENACS_SERVICE_NAME
postgresql	Redhat init scripts during boot	/etc/init.d/postgresql	/usr/local/pgsql/data/server.log		service postgresql start (Red Hat), /etc/init.d/postgresql start (Debian)

init - keeping AOLserver alive with inittab

This is an alternative method for keeping the AOLserver process running. The recommended method is to run AOLserver supervised.

This step should be completed as root. This can break every service on your machine, so proceed with caution.

• There are 2 general steps to getting this working.

  1. Install a script called restart-aolserver. This script doesn't actually restart AOLserver - it just kills it.

  2. Ask the OS to restart our service whenever it's not running. We do this by adding a line to /etc/inittab.

  Calling restart-aolserver kills our service. The OS notices that our service is not running, so it automatically restarts it. Thus, calling restart-aolserver effectively restarts our service.

• This script needs to be SUID-root, which means that the script will run as root. This is necessary to ensure that the AOLserver processes are killed regardless of who owns them. However the script should be executable by the web group to ensure that the users updating the web page can use the script, but that general system users cannot run the script. You also need to have Perl installed and also a symbolic link to it in /usr/local/bin.

  [joeuser ~]$ su - 
  Password: ***********
  [root ~]# cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/restart-aolserver.txt /usr/local/bin/restart-aolserver
  [root ~]# chown root.web /usr/local/bin/restart-aolserver
  [root ~]# chmod 4750 /usr/local/bin/restart-aolserver
  [root ~]# ln -s /usr/bin/perl /usr/local/bin/perl
  [root ~]# exit

• Test the restart-aolserver script. We'll first kill all running servers to clean the slate. Then, we'll start one server and use restart-aolserver to kill it. If it works, then there should be no more servers running. You should see the following lines.

  [joeuser ~]$ killall nsd
  nsd: no process killed
  [joeuser ~]$ /usr/local/aolserver/bin/nsd-postgres -t ~/var/lib/aolserver/service0/nsd.tcl
  [joeuser ~]$ restart-aolserver service0
  Killing 23727 
  [joeuser ~]$ killall nsd
  nsd: no process killed

  The number 23727 indicates the process id(s) (PIDs) of the processes being killed. It is important that no processes are killed by the second call to killall. If there are processes being killed, it means that the script is not working.

• Assuming that the restart-aolserver script worked, login as root and open /etc/inittab for editing.

  [joeuser ~]$ su -
  Password: ************
  [root ~]# emacs -nw /etc/inittab

• Copy this line into the bottom of the file as a template, making sure that the first field nss1 is unique.

  nss1:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nobody -g web -t /home/joeuser/var/lib/aolserver/service0/nsd.tcl

• Important: Make sure there is a newline at the end of the file. If there is not a newline at the end of the file, the system may suffer catastrophic failures.

• Still as root, enter the following command to re-initialize /etc/inittab.

  [root ~]# killall nsd    
  nsd: no process killed
  [root ~]# /sbin/init q

• See if it worked by running the restart-aolserver script again.

  [root ~]# restart-aolserver service0
  Killing 23750

If processes were killed, congratulations, your server is now automated for startup and shutdown.

external monitoring of server uptime

https://openacs.org/doc/uptime.html

starting aolserver before postgresql

Add a pause to the aolserver "run" script, for example:

    sleep 15

Alternately, John Sequeira suggests adding this code to the run script:

pid=`pidof -s postmaster`
while !([ $pid ] && /etc/init.d/postgresql status > /dev/null 2>&1)
do
pid=`pidof -s postmaster`
echo "checking...not yet"
sleep 1
done

run AOLserver on port 80 (or <1024) To run AOLserver on a port below 1024 (normally, for a webserver use port 80), edit the run script. /var/lib/aolserver/service0/etc/daemontools/run script according to the documentation found there (namely: Add the -b yourip:yourport switch)

Troubleshooting AOLserver

Check the serverlog 

To set up real-time monitoring of the AOLserver error log, from the shell, type

less /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/openacs-dev-error.log

 

F to show new log entries in real time (like tail -f)
C-c to stop and F to start it up again. 
G goes to the end.
? searches backward 
/ searches forward.  

Cannot view sample AOLserver welcome page There may be a problem with the server configuration. Start by viewing the AOLserver log, which is in /usr/local/aolserver/log/server.log. You should also try to find lines of the form:

[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: nssock: listening on http://localhost.localdomain:8000 (127.0.0.1:8000)
[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: accepting connections

If you can find these lines, try entering the URL the server is listening on into your browser. If you cannot find these lines, there must be an error somewhere in the file. Search for lines beginning with the word Error instead of Notice.

The sample-config.tcl file grabs your address and hostname from your OS settings.

set hostname        [ns_info hostname]
set address         [ns_info address]

If you get an error that nssock can't get the requested address, you can set these manually. If you type 0.0.0.0, AOLserver will try to listen on all available addresses. Note: ns_info address doesn't appear to be supported in current versions of AOLserver.

set hostname        [ns_info hostname]
#set address         [ns_info address]
set address 0.0.0.0

NsTclInitObjs: sizeof(int) < sizeof(long) This is a 64-bit compile problem that keeps Aolserver from starting. An error detection check in file nsd/tclobj.c is causing the error, and needs to be commented out. Wrap the following code with the C style /* */ comments (as shown), then rebuild. See https://openacs.org/forums/message-view?message_id=309887 for more info.

/*
    if (sizeof(int) < sizeof(long)) {
        Tcl_Panic("NsTclInitObjs: sizeof(int) < sizeof(long)");
    }
*/

Cannot view the OpenACS login or OpenACS Installation: Welcome page. View your error log (/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log) to make sure the service is starting without any problems. The most common errors here are trying to start a port 80 server while not root, failing to connect because of a firewall, and aolserver failing to start due to permissions errors or missing files. If you need to make changes, don't forget to kill any running servers with killall nsd.

Modifying AOLserver configuration config.tcl

• httpport - If you want your server on a different port, enter it here. The Reference Platform port is 8000, which is suitable for development use. Port 80 is the standard http port - it's the port used by your browser when you enter http://yourserver.test. So you should use port 80 for your production site.

• httpsport - This is the port for https requests. The Reference Platform https port is 8443. If http port is set to 80, httpsport should be 143 to match the standard.

• address - The IP address of the server. If you are hosting multiple IPs on one computer, this is the address specific to the web site. Each virtual server will ignore any requests directed at other addresses.

• server - This is the keyword that, by convention, identifies the service. It is also used as part of the path for the service root, as the name of the user for running the service, as the name of the database, and in various dependent places. The Reference Platform uses $OPENACS_SERVICE_NAME.

• db_name - In almost all cases, this can be kept as a reference to $server. If for some reason, the tablespace you are using is different than your servername, then you can set it here. You should have a good reason for doing this.

• servername - This is just a *pretty* name for your server.

• user_account - The account that will both own OpenACS files and connect to the database (for Postgresql).

• debug - Set to true for a very verbose error log, including many lines for every page view, success or failure.

AOLserver is very configurable. These are some of the more commonly changed settings. For more options, read the AOLserver docs.

AOLserver command line

See http://www.aolserver.com/docs/admin/tech.html