#openacs

Step (1): Create a new package

Go to ACS Site-Wide Administration and it’s Package Manager. At the bottom you can Create a new package

Choose a short readable package key and name. Choose to inherit from templates in order extend on XoWiki. You specifically don’t want to implement subsite semantics (just on a sidenote). Everything else is up to you.

If everything went accordingly, you’ll get a screen listing all the details for your new package.

Next to other packages you will now have a dedicated package in your packages folder of your openacs distribution:

(2) Setup Dependencies and Provides

We want to extend on XoWiki, therefore we need to somehow specify that somewhere. On the summary page of your newly created package scroll down and click Dependencies and Provides

Click “Add a service extended by this package” and select XoWiki.

After setting up the extension you will now be able to build on XoWiki. What does this mean. Basically two things:

Reusability & Extendibility: By extending XoWiki you will benefit from all features already present within the XoWiki package, thus reusing XoWiki technology. On top of that you can extend functionality in order to customize your XoWiki based application or build new features which are not present in XoWiki.

(3) Parameter Page

When looking at the parameter page, you will now be able to use parameters based on the XoWiki application and you can define separate parameters for specifically for your package:

In order to setup custom parameters, go to ACS Site-Wide Administration / Package Manager and click on the name of your package (Xowiki Sample Application). There, you can click on Parameters under the Manage headline:

Simply click “Add new parameter” to specify details for your parameter.

This will result in an entry on the parameter page of XoWiki Sample Application

You can access this parameter via the XoWiki procedure called get_parameter

An example would be

set title [$package_id get_parameter PackageTitle [$package_id instance_name]]

(4) Prototype Pages

Read up on Prototype Pages in the official XoWiki Documentation

Create a prototype directory and index.page file in your XoWiki Sample Application folder (xowiki-sample-app/www/prototypes/index.page). It should contain the following basic setup to get started:

You basically define a starting point for your wiki. A simple index page. If you delete it, it will be created automatically from the prototype defined in your XoWiki Sample Application. The convenience here, is that you can define your own custom index page with your package - this might come in handy when deploying your application and providing a starting point. You can edit this page with your wiki and customize it to your likes. 

(5) Templates

Templates are based on ACS-Templating. The documentation can be found here. 

To get started simply copy the structure from your xowiki folder over to your xowiki-sample-app. You need a template folder located in resources: /xowiki-sample-app/resources/template. Now copy over view-default.adp from xowiki into your empty templates folder. In order to demonstrate functionality remove the title in the template and name the file view-example.adp

Note that I only changed things around at the adp placeholders. The top stuff concerns xowiki’s menu structure, which you can also customize in this case. For example to include or hide additional links for users.

Now all you need to do is specify that you are using view-example.adp as your template file in the parameter page of your sample application. (Default Setting: view-default)

When refreshing your index page from the sample application the title should be gone. (demonstration wise)

With this setup you can start designing your website based on XoWiki in a separate package (xowiki-sample-app).

If you need a fresh slate to work with you can also issue a pull request from this xowiki-sample-app via github after creating a new OpenACS application.

https://github.com/michaelfeurstein/xowiki-sample-app.git

(0) If you don't have the script from part 1 - go grab it

https://github.com/gustafn/install-ns/blob/master/install-oacs.sh

(1) Check your variables before running the script

sudo ./install-oacs.sh

especially check that the following are set correctly

pg_dir=/opt/local/lib/postgresql94/ install_dotlrn=1

somewhere along the lines there is another pg_dir

pg_dir=${pg_dir}

check that psql is pointing to your current psql install

cd /opt/local/bin sudo ln -s /opt/local/lib/postgresql94/bin/psql psql

(2) Be sure to start postgresql94 server

sudo launchctl start org.postgresql.mifeurst

(3) Make sure cvs installed

port search cvs sudo port install cvs

(4) Run the install script

sudo bash ./install-oacs.sh build

(5) Configure your setup

ns_section "ns/db/driver/postgres" ns_param      pgbin   "/opt/local/lib/postgresql94/bin/"

Check that db_host db_port and db_user are set correctly

set address 0.0.0.0

(6) Start naviserver with the openacs config

As already shown in part 2 of this tutorial writing you will need to customize your openacs-5-8-config.tcl file in order to connect to the correct database. Note that the needed oacs-5-8 database was already created via the install script from above. So no need to create one manually.

sudo /usr/local/ns/bin/nsd -t /usr/local/ns/conf/openacs-5-8-config.tcl -u nsadmin -g nsadmin

(7) Per default OpenACS is installed here

/var/www/oacs-5-8/openacs-4

You’ll find logs, and process ids in the log directory

(8) In my case I got an error

Error: Error parsing queryfile /var/www/oacs-5-8/packages/acs-tcl/lib/page-error.xql: invalid command name "dom" invalid command name "dom"    while executing "dom parse -simple [lindex $args 1]"    (procedure "xml_parse" line 4)    invoked from within "xml_parse -persist $stuff_to_parse"    (procedure "db_qd_internal_parse_init" line 4)    invoked from within "db_qd_internal_parse_init $whole_file $file_tag"    (procedure "db_qd_internal_load_queries" line 15)    invoked from within "db_qd_internal_load_queries $stream $file_path"    (procedure "db_qd_internal_load_cache" line 9)    invoked from within "db_qd_internal_load_cache $file_path"

When further inspecting the error log one finds this:

error reading package index file /usr/local/ns/lib/tdom0.8.3/pkgIndex.tcl: expected version number but got "0.8.3"load"

Add a space after 0.8.3 so /usr/local/ns/lib/tdom0.8.3/pkgIndex.tcl looks like this:

package ifneeded tdom 0.8.3 "load [list [file join $dir libtdom0.8.3.dylib]];         source [list [file join $dir tdom.tcl]]"

Now restart your OpenACS instance.

(9) Navigate to localhost:8000

You should see a welcome page prompting for further steps to install openACS.

If you look through your error.log closely you’ll also see:

Notice: Bootstrap: Installation is not complete - sourcing the installer

Follow the installer via the web interface and setup your OpenACS instance.

After a successful installation your database should include some new entries:

(10) Start your server and go places

Index: http://localhost:8000/

Site-Wide Administration: http://localhost:8000/acs-admin/

Package Manager: http://localhost:8000/acs-admin/apm/

Also note that now your error.log will include the following line:

Notice: Bootstrap: Done loading OpenACS

You now have a working installation of OpenACS with NaviServer and PostgreSQL installed. 

Continue by installing Developer Support via the install interface from the repository. Start by going the package manager's installation page:

http://localhost:8000/acs-admin/install/

(11) Read up on the official documentation

You will probably want to start out with a simple package installation either as a front end application or a backend service.

The openACS documentation is pretty massive and in depth - so go ahead and dive in!

Introduction to packages in OpenACS: http://openacs.org/doc/packages.html Package Development Tutorial: http://openacs.org/doc/tutorial-newpackage.html Getting Started: http://openacs.org/storage/view/tutorial%5C/OpenACS_Tutorial.pdf Introduction to the concept of ACS Objects: http://openacs.org/doc/objects.html 

Enjoy!

Appendix A

You will probably want to have several instances of openacs around to test things or maybe have a development, staging, production workflow. In my case, I like to have a personal playground instance (sandbox?) and a development instance for each project to work on. When installing such an instance the following needs to be kept in mind:

1) Install a new instance via the install-oacs.sh script sudo bash ./install-oacs.sh build

2) Move/Rename the fresh installation sudo mv /var/www/openacs-5-9 /var/www/openacs-5-9-myProject

3) Move/Rename the openacs config file sudo cp /usr/local/ns/conf/openacs-config.tcl /usr/local/ns/conf/openacs-myProject-config.tcl

4) Be sure to have the correct configuration set port set server  set db_name

5) Rename the fresh openacs database ALTER DATABASE "oacs-5-9" RENAME TO "openacs-5-9-myProject-db";