Forum OpenACS Development: install documentation of AOLserver

We have many (too many) install guidelines for the basic installation, which are in different states and suggest to install different versions of packages. Putting this on a wiki is not the solution to get a simpler and consolidated version, but this rather leads to increase of the manifoldness. For example, https://www.openacs.org/xowiki/tcl-install refers first to Tcl 8.4.7 then to 8.4.13, where the actual and strongly recommended version for threaded applications is 8.4.14. i can certainly edit this page, but this is not the solution.

For a beginner, it is painful to go to all the sections/pages and use cut&paste or whatever to get AOLserver installed in a useful way. One can see this as an educational exercise to get familiar of what's used in the system, but most likely, many people will be turned away.

Why do we not suggest to use Malte's script? http://cognovis.de/developer/en/aolserver_install

It's not perfect, and should be commented in more detail, but this is certainly a first step, and leads to sane source and install structure. It takes care of all required modules, and best-of-all, it is used and maintained.

Some comments about the script:

• why does the script use tclllib 1.7 and not 1.9?
  
• Malte, for what do you use dqd_utils?
  
• for tdom, we do not use --with-aolserver and --disable-tdomalloc. Why is this there?

We use as well nscrypto, which has a blowfish implementation.

This script can be the suggestion "how to install AOLserver from scratch on a unix system meeting the requirements of OpenACS 5.3" and it should say, on which kind of systems it was tested. Or course, there will other pages for other OSes, or for distros, etc.

"We have many (too many) install guidelines for the basic installation, which are in different states and suggest to install different versions of packages. Putting this on a wiki is not the solution to get a simpler and consolidated version, but this rather leads to increase of the manifoldness. For example, http://www.openacs.org/xowiki/tcl-install refers first to tcl 8.4.7 then to 8.4.13, where the actual and strongly recommended version for threaded applications is 8.4.14"

The content from tcl-install comes from https://openacs.org/doc/current/aolserver4.html.

The "current" docs at https://openacs.org/doc/current/ are pretty much deprecated by lack of upkeep even if the OCT has not made a decision in which way the docs should be continued.

The wiki is leading to a consolidated version. The doc/current docs are for installing by source code, and include innumerable short cuts and a maze of cross references depending on the flavor of linux one is using and the options one wants to install.

Readers have to wade through and attempt to ignore a significant part of the content because it refers to other *nix flavors. Forum history shows how readers (myself included) frequently misread and either accidently miss or execute too many commands as a result of poor distinction between special cases.

With the wiki version, readers will have about 1 or 2 more urls to go through, yet less reading of content (words etc). One requirement in the wiki docs is to have readers only read what is relevant for their task at hand. Printing out the docs in both cases for any one particular *nix will show a decrease of reading of about 40% or more! That also translates to fewer chances to make mistakes etc.

Gustav, the "8.4.7" in the tcl-install page is only showing an example of what a function returns. Is that really the largest criticism you can express? Certainly the wiki documentation is not yet perfect, yet it still meets much more of the documentation requirements than the doc/current version.

Why not focus your constructive criticism of the docs where your expertise is needed most ie. in the engineering docs (including platform docs) which I am told are full of outdated material... at least, that is the rumor. I cannot tell what is accurate there without much pondering and meditation.

Generally, I wouldn't compile from source if the distro already provides packages. Specifically, we're running AOLserver on Ubuntu using packages tcl8.4, tcl8.4-dev, and tdom. (Configure --with-tcl=/usr/lib/tcl8.4 .)

Sure, packages are not always the very latest; tcl8.4 gives you 8.4.13 (with thread support). How is 8.4.14 superior? Is it worth the clutter?

Using the source for the install standard allows all distros to have a common basis from which to work from. It is pretty straight forward to identify dependencies and build options.. and to build scripts and installers for specific distros.

The original ACS docs used RedHat as a basis. Now, RedHat has.. RedHat Enterprise and Fedora.. The docs would be less useful to Ubuntu and FreeBSD and Windows users, for example, if they just instructed to use RPMs --not to mention that RPMs were not always available for some software required by a recent OpenACS release --libxml2 and the latest stable tcl release(s) for example.

The immediate convenience and usefulness of any specific install script is limited to the extent that it actually works without errors in a particular distro. If one happens to be using a different distro, one would have to likely learn the idiosyncrasies of 2 distros for the script to be useful --and that can require learning the idiosyncrasies of a 3rd *nix to figure out where the "norm" is.

Since Malte's script is mentioned, let's consider look at how that might break on something other than a Debian install. 1) It assumes one has installed Aolserver4.5. What if the user wants to use nsopenssl? Currently, it is not clear if nsopenssl will work with 4.5. 2) the script depends on wget. Wget is not directly available on many distros. One has to download it or know the distro's alternate (and how wget works by default since no flags are shown). 3) the script uses "make". Some distros invoke gcc with "gmake" instead of "make". 4) Did I mention that bash is not necessarily the standard shell? 5) Daemontools is problematic in certain distros or environments also. Anyway, a simple install script for 1 distro is a headache for another. Besides using an automated installer with it's own build process, one concievably could use tcl to build custom scripts that work under various distros, since tcl is fairly platform independent for our cases, but that's another install method. Anyway, to keep the docs simple, a standard was created that has value regardless of the specific distro.

Malte, that's great about nsopenssl.. I hadn't seen any reports about it's stability for 4.5 yet.

For the record, the contributions of distribution specific install scripts (including your's Malte) are a tremendous value to the OpenACS community. I personally appreciate the different styles that each expresses, and have used those contributions to help improve the reference platform docs. My comments above were not meant in anyway to demean the install scripts etc. I intended only to show the importance of standardized, generic *nix install as a primary reference source for these scripts in light of Gustaf's comments about their contributing to an "increase of the manifoldness" of the docs.

Hope that clarifiies.

cheers,

Torben

Couple of answers:

the docs contain ... innumerable short cuts and a maze of cross references ...

sorry, i don't see the docs as a shortcut, i rather conceive these as a maze. the script is for me a concise, executable shortcut, stating exactly, what's needed and how to install it. maybe, i belong to a different target group. i went through the maze in the past, tried to guess what's correct/wrong/outdated/not relevant etc.

... depending on the flavor of Linux one is using and the options one wants to install...

addressing all flavors is very ambitious. the flavors are moving targets. explaining the differences for all versions is a lot of work, and i have certain doubts, that this should be the goal of the OpenACS documentation. The script is a huge simplification by providing a full installation for the mainstream platforms. Every sysadmin knows what to do with it.

Readers have to wade through and attempt to ignore a significant part

my words: why do they have to do so? What is the target group? sysadmins? hardly. end-users? hardly.

Gustav, the "8.4.7" in the Tcl-install page is only showing an example of what a function returns. Is that really the largest criticism you can express?

well, at the time of my posting, the page was recommending to install 8.4.13. In the past i have altered more than once references to 8.4.13 into 8.4.14, but it seems that it was changed back. I was going to change it again, saw the comments by jiml, saw the 10 or more install pages on the left, wondered whether tcllib or XOTcl might be a subsystem, therefore the it should go to a different page, or not, wondered, what is meant in general by a subsystem, wondered, whether one should add warning not to run OpenACS on a reasonably busy site with Tcl 8.4.7, looked on my watch, saw that i have to prepare some meetings, and asked myself and the forum, whether or not this is a suitable and maintainable approach, what we are doing. Only criticism? please read me posting again. Btw, who is Gustav?

Why not focus your constructive criticism...

My posting is more constructive suggestion (by suggesting an alternative path) than a destructive criticism (saying what's wrong). I have a demanding job which has nothing to do with OpenACS - so i have limited capacities and i try to help by providing some support in the forums, in the core team, helping to fix the problems of openacs.org, or developing xotcl-core/xowiki further, and so on.

Has the OCT decided where the "supported" standard location is for installing XoTcl and tcllib in the context of the reference platform

The OCT does not have to decide that since it is clear that the standard place for these components is installed AOLserver tree, that is: aolserver/lib, the same place, where tdom should be installed to (and tclwebtest as well to be able to run the regression tests).

Christian: Sure, packages are not always the very latest; tcl8.4 gives you 8.4.13 (with thread support). How is 8.4.14 superior? Is it worth the clutter?

8.4.14 has several important bug fixes, especially for multi-threaded Tcl applications (aolserver/naviserver are among the largest and most demanding multi-threaded Tcl applications available). A couple of Tcl commands in versions up to 8.4.13 used C library functions that were not multi-thread safe. Zoran fixed this for 8.4.14. Clutter: Tcl should be installed with --prefix=/usr/local/aolserver, or aolserver-4.5. I strongly recommend to compile all Tcl C-extensions and aolserver modules with the same tcl-include files, which should be installed in .../aolserver/include. If one mixes versions, he asks for troubles. By installing into the AOLserver install tree, there is no conflict with system updates, or other applications needing certain versions of tcl, etc.

Dirk: A regular OpenACS developer should be happy with the packages provided by Debian stable: to my own astonishment all the necessary packages for OpenACS (save the dreadful daemontools) are even in the oldest possible Debian release.

Dirk, in general, i agree with you: it should. The question is, what "being happy" means: being able to compile and start or to run reliably. AOLserver/NaviServer are demanding applications. We have a few quite busy OpenACS installations, some of these had crashes that went away by upgrading to 8.4.14. It is certainly less work to install Tcl within the AOLserver tree and compile the needed c components with that version than arguing with package maintainers. What do you do if they release a version of tcl that is not tested with AOLserver? What's so bad about giving AOLserver it's own Tcl version, with which it is known to work reliable? Are you concerned that Tcl might not compile? About the time Tcl takes to compile? About the disk space? Over the last half year i made at two important fixes to the AOLserver c-sources, one of these was stopping openacs.org on a nightly basis. It is not clear, when the next version of AOLserver will come out, and if or when it will make it's way into the various distributions. Malte's script takes care of these things and it is less work to use it.

Certainly, having package maintainer for OS-specific distros for AOLserver, the needed aolserver-modules, OpenACS and dotlrn would be great, but we don't have it. Btw, one of my people has developed such a suite for FreeBSD, but it is not committed yet(see: http://www.matuska.org/martin/freebsd/).

Hope this helps.

best regards
-gustaf neumann

PS: Torben, sorry, if you feel personally attacked, that was not my intention.

PPS: That was my OpenACS timeslot for today.