Weblog

Developer Tutorial - Req.

Created by OpenACS community, last modified by Gustaf Neumann 07 Jul 2016, at 02:34 PM

Documentation Requirements for Developer Tutorials

By the OpenACS Community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003.

OpenACS developer tutorial documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here.

• list learning prerequisites to customize, fix, and improve OACS modules, and create new ones. You are expected to have read and understand the information [minimum requirements similar to adept at Using OpenACS Administrating Guide] before reading this guide.

• Refer to development documentation instead of duplicating here

• List suggestions for installing and setting up a development environment; these can be annotated links to the installation documentation

• Provide working examples that highlight the various subsystems, tcl environment, OpenACS protocols, aolserver template and ns_* commands, OpenACS templating, sql queries, db triggers, scheduling protocols, how to use the page contract, how to get the accessing user_id etc

• Show how to construct basic SQL queries using the db API,

• The life of an http request to a dynamic, templated page

• General rules to follow for stability, scalability

• Show the step by step customizing of an existing package that meets current recommended coding styles of OpenACS package development, by referring to developer resources.

• Use the ArsDigita problem sets and "what Lars produced for ACS Java" as inspiration for a PostgreSQL equivalent tutorial about developing a new OpenACS package including discussion of the significance of the package documentation templates

• Include a summary of important links used by developers

• Note any deprecated tools and methods by linking to prior versions instead of describing them in current docs

hstore

Created by Michael Aram, last modified by Gustaf Neumann 12 Apr 2016, at 10:39 AM

hstore is a postgresql module, which is used optionally by newer versions of xowiki and xowf (xowiki content flow) to provide quick access to the "instance_attributes" (the per-form or per-workflow attributes not part of the native content repository data model). The supporting functions (creating indices, etc) are currently mostly part of the xowiki sources (earlier: xowf).

Under Ubuntu, you can install hstore via:

    psql -d <yourdb> -tAc "create extension hstore"

You can then verify the successful installation on the ds/shell using:

    ::xo::db::has_hstore

Monitoring Naviserver

Created by Gustaf Neumann, last modified by Gustaf Neumann 10 Oct 2015, at 02:42 PM

Munin is a popular web-based tool to monitor several website. Munin provides a simple plugin mechanism for adding new kinds of sources, such as e.g. the NaviServer plugins for monitoring NaviServer.

The monitoring information collected by munin can be placed at different web servers, one finds usually information about apache and friends. In general older versions of munin (before 2.0) supported only static pages, whereas newer version support as well dynamic information (with additional features such as zooming).

For static munin pages, it is the easiest to place in OpenACS sites the output directory either under the main www directory, or under the subsite admin directory (packages/acs-subsite/www/admin/).

For the cgi-setup, one has to make sure to load nscgi in the statup files of NaviServer and to point the urls to the appropriate directories. The sample setup below uses the directories of munin as provided by a standard munin setup on an Ubuntu system.

ns_section ns/server/${server}/modules
   ns_param   nscgi        nscgi.so

ns_section "ns/server/${server}/module/nscgi"
   ns_param map  "GET /munin-cgi/munin-cgi-graph /var/www/cgi-bin/munin-cgi-graph"
   ns_param map  "GET /munin-cgi/static /etc/munin/static/"
   ns_param map  "GET /munin-cgi /var/www/cgi-bin/munin-cgi-html"

Vi as an OpenACS IDE

Created by OpenACS community, last modified by Monika Andergassen 05 Oct 2015, at 12:45 PM

In vim add the following in your .vimrc will help convert tabs to 4 spaces to meet part of the OpenACS coding standard.

set tabstop=4
set expandtab
set list
set listchars=tab:>.

It's also nice to have syntax highlighting by adding the following line

syntax on 

Also useful to use tagging features. In brief - run ctags -R in the root of the install or source tree.

At that point you can edit using vim -t procname or ::package::procname and go to the corresponding place in the code. From within the code, you can lookup functions by having the term highlighted and hit CTL-] - use CTL-T to go back.

Only works if you edit from the top directory, all tags are relative to there.

XOTcl

Created by Gustaf Neumann, last modified by Monika Andergassen 05 Oct 2015, at 12:43 PM

XOTcl is an object oriented extension for Tcl and required part of OpenACS installations since  TIP #87. The OpenACS package xotcl-core provides base functionality and integration with the OpenACS framework.

The current version of XOTcl is 1.6.7. Read about XOTcl motivations and  feature from http://media.wu-wien.ac.at/whatIsXOTcl.html. For more details about XOTcl, see XOTcl Homepage.

INSTALLATION of XOTcl:

One can get XOTcl e.g. in binary form from debian or it can be complied from source. The following instructions describe, how to compile XOTcl from source.

1. Get, compile and install XOTcl
   
   Get xotcl-1.6.7:
   

    cd /usr/local/src
    wget http://media.wu-wien.ac.at/download/xotcl-1.6.7.tar.gz
    tar zxvf xotcl-1.6.7.tar.gz         

   The following commands can be used to compile XOTcl and install it into the appropriate places of the specified aolserver. We assume that the aolserver is installed under /usr/local/aolserver:

    cd xotcl-1.6.7 
    CC=gcc;export CC 
    ./configure --enable-threads --enable-symbols --prefix=/usr/local/aolserver --exec-prefix=/usr/local/aolserver --with-tcl=/usr/src/tcl8.4.16/unix
   

   Use appropriate paths for aolserver4 and your tcl version.
   

   make 
   make install-aol

   After the "make install-aol" from the XOTcl sources, a file xotcl.tcl is installed in the directory /usr/local/aolserver/modules/tcl/ that handles .xotcl files and XOTcl serialization in the aolserver.

2. Restart your aolserver to load xotcl.
   

OpenACS Debian Install quicksheet

Created by Ryan Gallimore, last modified by Monika Andergassen 05 Oct 2015, at 12:32 PM

# PostgreSQL

 apt-get install postgresql postgresql-dev postgresql-doc 
 ln -s /usr/include/postgresql/ /usr/include/pgsql 
 ln -s /var/lib/postgres /usr/local/pgsql 
 ln -s /usr/include/pgsql /usr/local/pgsql/include 
 su postgres -c "/usr/lib/postgresql/bin/createlang plpgsql template1" 
 su postgres -c "createuser -a -d service1" 
 su postgres -c "createdb -E UNICODE service1" 
 

# AOLServer

 apt-get install aolserver4 aolserver4-nspostgres aolserver4-nssha1 aolserver4-nscache tdom

# OpenACS

 groupadd web 
 useradd -g web service1 
 mkdir /var/lib/aolserver 
 chown -R service1 /var/lib/aolserver 
 chgrp -R web /var/lib/aolserver 
 chmod -R 770 /var/lib/aolserver 
 exit 
 
 su - service1 
 cd /tmp 
 wget https://openacs.org/projects/openacs/download/download/openacs-5.1.5.tar.gz 
 cd /var/lib/aolserver 
 tar xzf /tmp/openacs-5.1.5.tar.gz 
 mv /tmp/openacs-5.1.5 service1 
 
 chmod -R 755 service1 
 chown -R service1.web service1 
 
 exit  

# Copy Files (where / is root of OpenACS instance):
# [edit hostname and address]
config.tcl => /etc/
set homedir                   /usr/lib/aolserver4
set bindir                    /usr/lib/aolserver4/bin


# init/d script:

    
 #!/bin/sh 
 # 
 # Start the AOLServer HTTP server. 
 #  
 
 NAME="OpenACS on service1" 
 SERVICEPATH=/var/lib/aolserver/service1 
 PATH=$PATH:/bin:/usr/bin:/sbin:/usr/sbin:/usr/local/pgsql/bin 
 trap "" 1 

 start() 
 { 
 
    echo -n "Starting web server: $NAME" 
    echo -e -n "\r" 
 
    #!/bin/sh  

    
    #we need to export the library stuff first 
    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib 
    export PATH=$PATH:/usr/local/pgsql/bin 
 
 
     # give time for Postgres to come up 
     sleep 1 
     exec /usr/sbin/aolserver4-nsd -it $SERVICEPATH/etc/config.tcl -u service1 -g web & 
 
     # For AOLserver 4 using privileged ports (usually < 1024), add the flag 
     # -b youraddress:yourport  
     echo "" 
 } 
 
 
 
 stop() 
 { 
     echo -n "Stopping web server: $NAME" 
     killall aolserver4-nsd 
     echo ""   
 } 
 
 
 case "$1" in 

   start)   
     start 
     ;; 
 
   stop) 
     stop   
     ;; 
 
 
   restart) 
     stop 
     sleep 2 
     start 
     ;; 
 
   *) 
     echo "Usage: /etc/init.d/$NAME {start|stop|restart}" 
     exit 1 
     ;;   
 esac 
 
 echo -n -e "\c\r\n" 
 exit 0 
 
 
 # End of script  
  

# avoid pid not found errors in the log

 mkdir /usr/lib/aolserver4/log 
 chown root:web /usr/lib/aolserver4/log 
 chmod 775 /usr/lib/aolserver4/log 

# Set openacs to start on boot

 update-rc.d openacs-service1 defaults 
 chmod u+x openacs-service1   
 ln -s /var/lib/aolserver/service1 

Install AOLserver 4.5

Created by Malte Sussdorff, last modified by Monika Andergassen 05 Oct 2015, at 12:12 PM

If you want to install AOLserver 4.5 you could follow the instructions for AOLserver en:aolserver-install and replace 40r10 with 4.5 (more or less ...).

Alternatively follow the instructions or download it as a shell script (recommended) or download a full archive aolserver45-oacs.tar.bz2.

If on "OS X" the install fails for nspostgres with undefined symbols, execute the following command:

gcc -pipe -dynamiclib -install_name /usr/local/aolserver45/lib/libnspostgres.dylib  -o libnspostgres.dylib nspostgres.o -L/usr/local/aolserver45/lib -lnsd -lnsthread -L/usr/local/aolserver45/lib -ltcl8.4   -lpthread -framework CoreFoundation   -lnsdb -L/usr/local/pgsql/lib -lpq

Installing OpenACS on FreeBSD

Created by OpenACS community, last modified by Gustaf Neumann 04 Sep 2014, at 07:33 PM

OpenACS and .LRN are available via FreeBSD ports. See en:openacs-system-install-freebsd-ports.

The following notes are useful if you decide to follow the OpenACS manual installation process using FreeBSD. These notes include points where a manual FreeBSD install differes from the slow, manual en:openacs-system-install.

The following information is pulled from: https://openacs.org/forums/message-view?message_id=312823 and https://openacs.org/forums/message-view?message_id=136910 and https://openacs.org/forums/message-view?message_id=312823

The OpenACS Reference Platform uses shell scripts written for bash, which is the standard Linux shell. If you are using a different shell, you will need to substitute your shell's conventions for setting environment variables when appropriate, and install bash to work with the scripts. Substitute fetch when the instructions suggest you use wget to download software.

Note that on most linux distributions, GNU Make is simply named make and there is no gmake, whereas on BSD distributions, make and gmake are different --use gmake.

Change the period separating user.group in chown commands to use a colon ":" instead. For example,

chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME

becomes:

chown -R $OPENACS_SERVICE_NAME:$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME

Should you decide to install OpenACS from source using general en:openacs-system-install instructions, refer to these notes for changes:

Installing tdom

FreeBSD can use the standard tdom from ports when installing manually, without going the extra step of installing tdom within the aolserver src tree.

Installing en:postgresql

Creating postgres user

To set defaults for new users or special service users you may create, edit the file /etc/share/skel/dot.profile instead of /etc/profile

To create the user, we need to add more parameters to match what is expected from creating a user in linux.

[root src]# mkdir -p /usr/local/pgsql
[root src]# pw groupadd -n web
[root src]# pw useradd -n postgres -g web -d /usr/local/pgsql -s /bin/bash
[root src]# chown -R postgres:web /usr/local/pgsql /usr/local/src/postgresql-7.4.7
[root src]# chmod -R 750 /usr/local/pgsql
[root src]#
mkdir -p /usr/local/pgsql
pw groupadd -n web
pw useradd -n postgres -g web -d /usr/local/pgsql -s /bin/bash
chown -R postgres:web /usr/local/pgsql /usr/local/src/postgresql-7.4.7
chmod -R 750 /usr/local/pgsql

Set PostgreSQL to start on boot

[root ~]# cp /tmp/openacs-5.2.0d1/packages/acs-core-docs/www/files/postgresql.txt /usr/local/etc/rc.d/postgresql.sh
[root ~]# chown root:wheel /usr/local/etc/rc.d/postgresql.sh
[root ~]# chmod 755 /usr/local/etc/rc.d/postgresql.sh
[root ~]# 
cp /tmp/openacs-5.2.0d1/packages/acs-core-docs/www/files/postgresql.txt /usr/local/etc/rc.d/postgresql.sh
chown root:wheel /usr/local/etc/rc.d/postgresql.sh
chmod 755 /usr/local/etc/rc.d/postgresql.sh

Test the script

[root ~]# /usr/local/etc/rc.d/postgresql.sh stop
Stopping PostgreSQL: ok
[root ~]# 

If PostgreSQL successfully stopped, then turn it back on because we'll use it later.

[root root]# /usr/local/etc/rc.d/postgresql.sh start
Starting PostgreSQL: ok
[root root]#
/usr/local/etc/rc.d/postgresql.sh start

PostgreSQL performance tuning

See man syctl, man 5 sysctl and man 5 loader.conf.

Installing Libthreads 2.6.5

cd /usr/local/src/aolserver/
fetch http://mesh.dl.sourceforge.net/sourceforge/tcl/thread2.6.5.tar.gz
tar xzpf thread2.6.5.tar.gz
cd thread2.6.5/unix
less ../README
../configure --help
../configure --enable-threads --prefix=/usr/local/aolserver --exec-prefix=/usr/local/aolserver --with-aolserver=/usr/local/aolserver --with-tcl=/usr/local/lib/tcl8.4-threads
gmake
gmake install

Creating users

We need to add more parameters to have user environments match the linux ones expected by the en:openacs-reference-platform.

Create users this way:

[root root]# mkdir -p /home/$OPENACS_SERVICE_NAME
[root root]# pw useradd -n $OPENACS_SERVICE_NAME -g web -d /home/$OPENACS_SERVICE_NAME -s /bin/bash
[root root]#
mkdir -p /home/$OPENACS_SERVICE_NAME
pw useradd -n $OPENACS_SERVICE_NAME -g web -d /home/$OPENACS_SERVICE_NAME -s /bin/bash

Install Tcl

Created by OpenACS community, last modified by Jim Lynch 06 Sep 2013, at 12:21 AM

Check suitability of a previously installed TCL.

Start tcl (type tclsh or find it using which tclsh).

[root root]% info exists tcl_platform(threaded)
1
[root root]% info patchlevel
8.5.14
[root root]%

If the first command returns anything other than 1, then tcl is not threaded. If tcl is threaded and the version is 8.5 or higher, then installing tcl from source is optional.

 (jiml) Note that you will also need compiletime stuff so you can build things against that tcl; how to get it varies according to what OS and flavor thereof you run. Personally, I don't like to permit the operating system to dictate any versions of anything or have any influence over installing/removing, so I build the whole stack (these days, not including postgres) myself.

Install Tcl

Get TCL 8.5 (or higher). Download and install TCL 8.5 from source.

If you have not installed TCL already, download the latest TCL version from Sourceforge or http://www.tcl.tk/software/tcltk/downloadnow85.html

We are installing tcl in context with aolserver to use a consistent set of libraries when more than one version may be present. Use the same directory for aolserver here, that you will be using when installing aolserver from the en:aolserver-install page.

Remember that you have to be logged in as root to issue the following commands.

[root root]# mkdir -p /usr/local/src/aolserver40r10
[root root]# cd /usr/local/src/aolserver40r10
[root src]# wget http://heanet.dl.sourceforge.net/sourceforge/tcl/tcl8.5.14-src.tar.gz
[root src]# tar xfz tcl8.5.14-src.tar.gz
[root src]# cd tcl8.5.14/unix
[root unix]# ./configure --enable-threads --prefix=/usr/local/aolserver40r10
[root unix]# make install
[root root]# 
      

ref: https://openacs.org/doc/aolserver4.html

Pull info from: http://www.tcl.tk/software/tcltk/downloadnow85.html

Installing OpenACS on Redhat

Created by OpenACS community, last modified by Gustaf Neumann 20 Aug 2013, at 01:32 PM

Redhat publishes 2 versions of their OS, Fedora (FC) and Redhat Enterprise...

The quicksheet versions:

• naviserver-openacs: compile from scratch, including NaviServer (tested with Fedora Core 18)
• Forum discussion: https://openacs.org/forums/message-view?message_id=351022
• FC: en:OpenACSInstallGuide

You should know what you're doing when you use them.

Should you decide to Install OpenACS from source using general en:openacs-system-install instructions, refer to these notes for changes.

Some of these notes below are probably outdated by now, but might still give some useful hints for certain installations.

Notes for Installing Postgresql en:postgresql-install

If you install PostgreSQL 7.3.2 from the Red Hat 9 RPM, you can skip a few steps. These shell commands add some links for compatibility with the directories from a source-based install; start the service; create a new group for web service users, and modify the postgres user's environment (more information):

[root root]# ln -s /usr/lib/pgsql/ /var/lib/pgsql/lib
[root root]# ln -s /var/lib/pgsql /usr/local/pgsql
[root root]# ln -s /etc/init.d/postgresql /etc/init.d/postgres
[root root]# ln -s /usr/bin /usr/local/pgsql/bin
[root root]# service postgresql start
Initializing database:
                                                           [  OK  ]
Starting postgresql service:                               [  OK  ]
[root root]# echo "export LD_LIBRARY_PATH=/usr/local/pgsql/lib" >> ~postgres/.bash_profile
[root root]# echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bash_profile
[root root]# groupadd web
[root root]# su - postgres
-bash-2.05b$

ln -s /usr/lib/pgsql/ /var/lib/pgsql/lib
ln -s /var/lib/pgsql /usr/local/pgsql
ln -s /usr/bin /usr/local/pgsql/bin
service postgresql start
echo "export LD_LIBRARY_PATH=/usr/local/pgsql/lib" >> ~postgres/.bash_profile
echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bash_profile
groupadd web
su - postgres

... and then skip to the section in en:postgresql-install that deals with installing plpgsql.

Set PostgreSQL to start on boot

Red Hat RPM:

The init script is already installed; just turn it on for the appropriate run levels.

[root root]# chkconfig --level 345 postgresql on
[root root]# 

Red Hat from source:

[root src]# cp /var/tmp/openacs-5.2.0d1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
[root src]# chown root.root /etc/rc.d/init.d/postgresql
[root src]# chmod 755 /etc/rc.d/init.d/postgresql
[root src]# 
cp /var/tmp/openacs-5.2.0d1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
chown root.root /etc/rc.d/init.d/postgresql
chmod 755 /etc/rc.d/init.d/postgresql

Test the script.

[root root]# service postgresql stop
Stopping PostgreSQL: ok
[root root]# 

If PostgreSQL successfully stopped, then use the following command to make sure that the script is run appropriately at boot and shutdown. And turn it back on because we'll use it later.

[root root]# chkconfig --add postgresql
[root root]# chkconfig --level 345 postgresql on
[root root]# chkconfig --list postgresql
postgresql      0:off   1:off   2:on    3:on    4:on    5:on    6:off
[root root]# service postgresql start
Starting PostgreSQL: ok
[root root]#
chkconfig --add postgresql
chkconfig --level 345 postgresql on
chkconfig --list postgresql
service postgresql start

Red Hat defaults to starting services on 3-5. So, on Red Hat, PostgreSQL won't start on runlevel 2 unless you alter the above commands a little. This usually isn't a problem as Red Hat defaults to runlevel 3)