Forum OpenACS Q&A: Newbee documentation

Collapse
Posted by Aernout Schmidt on
1. Last month I have, as a newbee, been spending a lot of my (and other's) spare time on getting OACS-core, Search-OpenFTS and dotLRN- core to run on a dedicated server (Celeron 1000, 512M), (FreeBSD 4.6, Aolserver 3.4.2, Postgreslq-7.2.1) using several documentary sources. I have kept track of my misery and would be able to concoct a small manual for other newbies. Things like that do not make sense if not guided by someone more experienced. Is there someone out there who is willing to adopt this role?

2. The section on installation is finished (in Dutch, I need some time for translation). In real life I have things working, but extremely slow and I could really use some help and advise on configuring/tuning FreeBSD-Aolserver-Postgresql, being almost completele in the dark there. Is there someone out there who is willing to help on this section?

3. I will be working on the Tcl/adp and packages section during the next two months and expect the available documentation to be of great help there. A collaborative writing package in OACS/dotLRN would be a good thing though. Is anyone aware of such a thing being in existence?
Collapse
Posted by xx xx on
I suppose Torben is the one to contact for the newbies manual (https://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=0005RO&topic_id=OpenACS&topic=11).

For specific questions I suggest you post them on the Bboard.
But, if you like, you can contact me too (in Dutch). I would be glad to help you wherever I can.

Collapse
Posted by Aernout Schmidt on
Thanks, Aldert - I'll mail you
Collapse
Posted by Torben Brosten on
Aernout Schmidt, I am creating end-user documentation, and am also compiling a proposal for additions and changes to the Site and Content Administrators, and Beginning Developers documentation. (I'm starting to call the docs the OpenACS maze. =) Quite honestly, I think the documentation could best be organized in a database that sorts and filters the information according to reader's priorities and needs --but that is a discussion for later (when I am able create such a monster in OpenACS myself).

Most of the notes are gathered from board discussions and piecing together existing documentation. I'm sure your notes would be helpful to me, but I am not sure I would be much of a help to you at this time as I am in a similar predicament with OpenACS.

I suggest you post questions and comments to the board. This has important side-effects:

  1. more than 1 person may answer with more than one perspective on the topic
  2. there is a greater chance that someone will be inspired to write an eloquent explanation which can then be incorporated into the documentation
  3. the answer becomes immediately available for anyone who manages to find it via the forum search

For openACS, you will want to also contact the people mentioned for document contributions on this page: https://openacs.org/contribute (and keep me posted, with any notes you have, also: torben@kappacorp.com ).

For DotLRN, you should probably inquire in the dotLRN forum on who to contact: https://openacs.org/bboard/q-and-a.tcl?topic_id=15&topic=dotLRN%20Development

Collapse
Posted by Aernout Schmidt on
Torben, Aldert, thanks for your comments. I like Torben's suggestion to employ the question-answer format and we can try it out in this thread. We best focus on the next question first:

Q. For whom is the Q/A newbee documentation (emerging in this thread) supposed to be of interest?

A. For people like myself - i.e. people with some programming experience, professionally tied into MSWindows conditions and motivated to explore OpenACS on a DSL-connected FreeBSD server.

------------

For some coherence I suggest we sequentially address questions in the following areas:

1. What do I need before I start? (e.g., FreeBSD server; PuTTY, iXPLORE on desktop; a link to Philip and Alex's Guide);

2. Where and how do I get and store the relevant sources? (wget, cvsup, ports, aolserver, libxml, freebsd-aolserver-extras, aol-startscript, postgresql, postgres-headers, postgres-startscript, pgdriver, daemontools, openacs-core, openacs-packages, openacs-openfts-driver package, dotlrn-core)

3. How do I compile and configure aolserver and postgres?

4. How do I configure monitoring aolserver and postgresql as services?

5. How do I install OpenACS-core and -packages?

6. How do I configure FreeBSD, aolserver and postgres for some speed?

7. How do I install OpenFTS-driver?

8. How do I install dotLRN-core?

9. How do I install and configure external packages?

...

----------------------

I realise I have two subtopics in this response (the first Q/A tuple and a concept sequence).
Collapse
Posted by Torben Brosten on

Since you want to "tune" the applications etc. I understand that this document is to be a guide for beginning developers, sort of like the documentation at https://openacs.org/doc/ but for OpenACS 4.5.


>       1. What do I need before I start? (e.g., FreeBSD server;
>PuTTY, iXPLORE on desktop; a link to Philip and Alex's Guide);

General information about scalable dynamic web sites can be found at:

http://philip.greenspun.com/internet-application-workbook
http://philip.greenspun.com/wtr/dead-trees/
In lieu of a 4year education in Computer Science, learn the material contained in
the harddisk available from: http://aduni.org 

More specific information:
http://philip.greenspun.com/sql/  SQL for Web Nerds
http://philip.greenspun.com/tcl/  TCL for Web Nerds
See also the docs at Aolserver.com, postgresql.org, and the documentation
associated with the distribution of unix/linux you are using.
There are also various docs peppered throughout the forums that
need to be collected for this part of the docs.

Notes that some have managed to get OpenACS to work in some configurations of
Windows2000. See https://openacs.org/doc/openacs-4/win-install.html

>
>       2. Where and how do I get and store the relevant sources?
>(wget, cvsup, ports, aolserver, libxml, freebsd-aolserver-extras,
>aol-startscript,
>       postgresql, postgres-headers, postgres-startscript, pgdriver,
>daemontools, openacs-core, openacs-packages, openacs-openfts-driver
>package,
>       dotlrn-core)
>

These should be available via the links in the document "Installing on Unix/Linux"
as a part of https://openacs.org/doc/openacs-4/

>       3. How do I compile and configure aolserver and postgres?
>

In general, regarding compiling programs: 
http://www.tldp.org/FAQ/Linux-FAQ/porting.html#HOW-DO-I-COMPILE-PROGRAMS

>       4. How do I configure monitoring aolserver and postgresql as
>services? 

Do you want to verify that services are working? you might try:
http://uptime.openacs.org 
Uptime is discussed in Greenspun's "Philip and Alex's Guide to Web Publishing" 
as a case study in Chapter 15.

>
>       5. How do I install OpenACS-core and -packages?
>

See the section of OpenACS 4.5 documentation entitled "Install OpenACS 4.5"
available at https://openacs.org/doc/openacs-4/openacs.html

Once the system is operating and you have signed in as Administrator, a
"Congratulations!" page appears. The section "How to Add Functionality to Your
Site" addresses installing and managing packages.  

More documentation is available at http://your-local-installation/doc/
A package has to be installed to see its documentation. Go to the "Package
Manager" (linked from the front page), followed by "Install packages". Select the
packages you want to install, but do not "enable" them unless you are ready to use
them. Installing and enabling *all* packages will cause problems as there are
package conflicts (but I don't have a list of them at this time).

>       6. How do I configure FreeBSD, aolserver and postgres for
>some speed?
>

There are some unix commands and other info mentioned in the forums that help
address the monitoring of the system for tuning purposes. For example:

https://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=0005nN&topic_id=11&topic=OpenACS

https://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=0004ei&topic_id=11&topic=OpenACS

https://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=00052Z&topic_id=11&topic=OpenACS

Also note, as a scalable community system by design, the system is already
optimized for working well under moderate to heavy load.


>       7. How do I install OpenFTS-driver?
>
It's installed as a part of following the directions on the lower half of the page
at:

https://openacs.org/doc/openacs-4/nextsteps.html  Note that some other OpenFTS
preparations are made during the installation of other components of the system
prior to reaching this page.


>       8. How do I install dotLRN-core?
>

I think dotLRN-core is OpenACS-core, and that dotLRN packages install on top of
OpenACS, but I'm just guessing at this point as I have not tried it.

>       9. How do I install and configure external packages?

I understand that this is also addressed in the "How to Add Functionality to Your
Site" part of the "Congratulations!" page of your local installation.

Go to the "ACS Package Manager" linked from the ACS Admin page (
http://your-local-installation/acs-admin/ 
 ) or the "Congratulations!" page. Then follow the "Load a new package from a URL 
 or local directory" link.

Please someone correct me if I have miss stated something or there is a doc that states all of this.

Collapse
Posted by xx xx on
One thread turns into a Bboard this way.

Torben, would it be an idea to use the FAQ approach in your new forum?
For example with a category 'FAQ' where only the maintainer has permission to 'create a New thread'.

A FAQ thread: might have a FAQ as Title and a Link to a FAQ-doc where the answer is explained (probably a copy of the official doc).
Newbees, Designers, Admins etc could ask their question and others can learn from the questions too.
The maintainer could update the FAQ-doc.
With a new OACS release the FAQ-doc could serve a purpose when adjusting the official docs.

'Add a comment' which is used in the official docs, doesn't give the same flexibility.

Do whatever you think is best, Torben. The approach has drawbacks too (threads can become long for example) and let's not start the same discussion we had before.
I suppose you're in contact with Don about the new forum and probably Roberto Mello should be consulted when (pre)maintaining the official docs would be involved.
Collapse
Posted by Ben Koot on
Hi folks, I like the idea of using the FAQ section for this purpose, however, it would mean we need to create a group, activate the Faq module to that group, and facilitate members to the group to add answers to it. I am sure this approach will be more effective than having info stuck on the bboard. There's one drawback, it might need an editor that draws some kind of edits a final answer if there is such thing. This also hits another subject. The new OpenACS site seems to focus on OpenACS 4. I can undestand that, but, untill we have a fully operational 4 release, to replace 3.2.5 I feel we can't ignore the fact the majority of ACS users is, with the exeption of Greenpeace and dotLRN, most likely using older versions of the toolkit. It's not fancy stuff, there's little glory in it maybe, but from a newby point of view it at least offers a stable environment. So We might be wise add a section how to migrate from 3 to 4, and how can we use both systems running tandem untill we can forget about 3. I have seen a few answers in this area, but it would be interesting to hear about the issues others run into.

It's not just a technological issue, it's also marketing. I see some great improvements in 4 I would like to offer my clients, but am hesitant because of all the changes going on. The best of both worlds would be great, but is likely to confuse clients. The sooner we find an answer to this, the better. Cheers

Collapse
Posted by Torben Brosten on

Aldert and Ben, thank you for the thoughts on forum management. Note that this thread has nothing to do with the upcoming forums and how they will/should work. If anyone wishes to continue on the topic of forum operations, please start another thread.

Aernout, I am learning that the documentation presentation is very much tied to a chronological sequence. Deviating from the sequence will likely slow learning significantly, since access to some very useful documents and information depends on having a locally installed and working system. Here is the sequence as I understand it:

  1. read about the system in general
  2. install the system
  3. read more about the system via the installed and working system
  4. confirm one's understanding through experimentation (trial and error) on a local system, and digging through the code

The working system has some instructions presented in context with where the commands are issued --in the User/Admin Interface (UI) starting at http://your-local-installation/ . Also, package documentation is accessible via the web at http://your-local-installation/doc/

Others have recommended strongly "installing the system and giving it a whirl" etc. but I did not really understand why. I thought it was evangelism for the system, not due to a set sequence of access to documentation. My learning style is grounded in reading about something in great detail, and understanding it, before trying it. OpenACS documentation precludes this approach, perhaps for a good reason: there have been periods of rapid development, where documentation and code have evolved in significant increments. The labor associated with posting documentation for all versions, and maintaining them, has been avoided by connecting the documentation directly to each installation/revision. As development stabilizes, an "official release" is designated (and some documentation published). I would have learned much more, sooner, had I installed a local OpenACS 4.x pre-beta instead of waiting...

Thankfully, a significant portion of this information is now available prior to installing. See "Documentation for this installation of OpenACS" ( https://openacs.org/doc/index-3.html ) from https://openacs.org/doc/ This is great if one does not time or resources to dedicate to installing, but wants to find out more about the system.

Still, at this point, beginning developers will gain much from a working local installation.

Collapse
Posted by Ben Koot on
"installing the system and giving it a whirl" ... has one drawback, certainly if there is little readibly background information.

My 2 $.cents worth... By the time I  managed to make sense of things, I had created such a mess, and lost valuable time makings sense of error messages, I was forced to start all over again and again. How many newbies are willing to go through this process.  Effectively this woill not raly help in evangilism I feel. Even if it's the best way to learn, there must a simpeler format to get people started, and I feel Torben's approach could be the right one. One thing that I learned was that at first it seemed I would have to learn Tcl, as I was under the impression I had to change an awfull lot to make ACS modules do the things I needed, to discover later this is not the case. Once you know what you are looking at (which is helpfull if you start) it's releatively simple to put together a shopping list of items you need changed, and find help with those issues.
Cheers

Collapse
Posted by Aernout Schmidt on
Torben, Ben , Aldert - thanks for your comments. I agree with Torben about the importance of the sequence of presentation/treatment of subjects. I agree with Ben that this thread may explode into newer Babylon. It might work, however, if we stick to a few conventions. The thread might even provide a sound basis for some neatly edited and maintained information - e.g. in the available docbook?

The learning sequence suggested by Torben is valid, I think. However, I would suggest that the read-install-readmore-experiment workflow may be more effective at the granularity level of the 9 questions I mentioned in my last response than at the general system level as proposed by Torben.

I further suggest the convention, that I introduce the question under discussion with its first concept answer using Q# and A# - and that comments relate to this question until the next one is put to the fore. Comments might be categorised using read, install, readmore and experiment tags.

I will post the first Q/A tuple presently.
Collapse
Posted by Aernout Schmidt on
Q1 What do I need before I start?

A1 FreeBSD, PuTTY, iXplorer and some unix reading

read

Some of Philip Greenspun's work (e.g., this) and Calvo's article.

install

We assume you have two boxes available, one client (on some MSWindows OS) and one server (where FreeBSD-4.6.2, aolserver-3.4.2, postgresql-7.2.1, OACS4.x and dotLRN will live).

On your server you will need to install FreeBSD-4.6.2.

Get the file 4.6.2-disc.iso from the directory /pub/FreeBSD/releases/i386/ISO-IMAGES/4.6.2 from your nearest freebsd ftp mirrorsite (mine is ftp.nl.freebsd.org) and burn it on a CD.

Use the CD to install FreeBSD-4.6.2. It will take approximately an hour to follow steps 1-54 of the installation guide available at http://www.orchardlabs.com/library/freebsd/freebsd.

readmore

If you are new to unix, you will want to keep the relevant freebsd handbook URL amongst your favourites. It will further help to read the man pages of the cd, pw, su, mkdir, cp, mv, rm, edit, chown, chmod, make, gmake, find, script and makefile commands/issues. The shell command "man find" will show the man pages of find on the FreeBSD console used.

install

On your Windows box, download and install PuTTY from http://www.chiark.greenend.org.uk/~sgtatham/putty/. You will use it to provide a virtual server console on your windows box.

experiment

Read the PuTTY documentation and try it out. You cannot login as root. Using PuTTY you can su to root when logged in as a user that is a member of the wheel group. As root, you can use the script command to log the keystrokes and the console action - a handy tool for reflection. If your server does not print, you can install and use iXplorer on your Windows box (download and install from http://www.i-tree.org/gpl/ixplorer.htm) to transfer files between your server and your client box.
Actually, the sequence stems from Arsdigita's home study program (year 2000): http://web.archive.org/web/20000819083243/www.arsdigita.com/pages/jobs/home-study It might also stem from aD's bootcamp, but I do not know since I did not attend one. I, wrongly, thought this approach was canceled when Arsdigita stopped their home study program. As you can see, I was slow at figuring this out!

I bet the developers already know this process by habit, and the instructions have become implicit over time.

Here's more about the aD tools, from the above reference, that relates directly to this discussion: http://web.archive.org/web/20000816014129/www.arsdigita.com/asj/using-the-acs

There should be enough information here to create some sort of Beginning Developers documentation --which, for the record, is different than End-Users and Site/Content Admin documentation. I guess it should probably be put as at the beginning of the Developer documentation at: https://openacs.org/doc/openacs-4/acs-dev.html

Collapse
14: Q1 - read (response to 1)
Posted by Aernout Schmidt on
There is a lot of good material dispersed over the web. As preliminary reading Eve Ander's historic story will explain part of the forking of sources (Arsdigita, OpenACS, Red Hat ACS, dotLRN) and can be considered a mustread for newbees needing the context of material in order to assess its local meaning.

This is a good preliminary starting point for reading, but keep in mind its context is arsdigita (aD), not OACS.
Collapse
Posted by David Geilhufe on
Just to let folks know, I am also keeping an archive of newbie documentation with the intention of working to make OACS more accessible to new system admins (and also new developers).

Part of that was to check with Philip on the TCL/SQL for web nerds docs. They can be linked to off Philip's site, and we can include the sorce in our tarball, allowing us basically to deliver a home study course via tarball ;)

The other big project I'm interested in is trying to figure out if we can retool the Psets to be relevant to today's OACS.

Collapse
16: Q1-9 - read (response to 1)
Posted by Aernout Schmidt on
Eve Andersson's leture notes seems good introductory reading for beginning developers and beginning site/content admins. http://eveander.com/ gives the URL (that is not always live). The lecture notes cover many aspects of the series of questions under consideration. Context is aD.
Collapse
Posted by Aernout Schmidt on
If you have the server running FreeBSD-4.6.2, if you can access it through PuTTY and you are new to unix/FreeBSD the next series of experiments should provide enough FreeBSD fluency to help you through much of the steps ahead. Memorizing the basic system directory structure and its semantics (from the handbook) is useful.

1. Activate (as root user - in code listings denoted by the # prompt) the typescript log of your actions:

# script

2. Make (as root user) a new directory

# mkdir -p /usr/experiment/test

Check # man mkdir for the meaning of the -p option. As a matter of fact: check the man pages every time a command is suggested in the text and you do not know the meaning of it or its options and parameters.

3. Check your location in the file system (current directory):

# pwd

4. Change to the /usr/experiment/test directory:

# cd /usr/experiment/test

5. Edit the file blurb in that directory (it will be a new file):

# edit blurb

6. Create and save the textfile, experimenting with the on screen help.

7. Create a symbolic link from /usr/experiment/test/blurb to /blurb:

# ln -s /usr/experiment/test/blurb /blurb

8. Look at the characteristics of the files and directories in the file system root:

# ls -l /

9. Edit /blurb and notice its contents are and remain actually /usr/experiment/test/blurb's contents.

10. Print the contents of /blurb to your screen:

# cat /blurb

11. Make the new user "anotheruser" and give her a password:

# pw useradd -G wheel -d /home -n anotheruser

# passwd anotheruser

12. Make "anotheruser" owner of /blurb

# chown -R anotheruser /blurb

13. Look again at the characteristics of the files and directories in the file system root:

# ls -l /

14. Become "anotheruser" and force the "anotheruser" enviromment to become active:

# su - anotheruser

15. Look again at the characteristics of the files and directories in the file system root and note the differences. Note that anotheruser's prompt is $:

$ ls -l /

16. Check your current directory (the - option of the su command forces the new user's home directory):

$ pwd

17. Become the root user again:

$ exit

18. Stop logging your actions (Ctrl-c interrupts the active logging process started from the PuTTY console earlier):

# Ctrl-c

19. Find the location of the file "typescript" (containing your log) - start searching in the file system root - print the result on your console:

# find / -name "typescript" -print

20. Copy the relevant typescript file to the home directory (found in step 16) of "anotheruser"

# cp "founddiretory"/typescript "anotheruserhomedirectory"/.

21. Start iXPLORER on your windows box - (it behaves peculiar on my W2000 environment: after starting it I get a black screen. Only after selecting and leaving the "task list" option after ctrl-alt-del, the interface becomes visible).

22. Connect to your server as "anotheruser".

23. Transfer the file "blurb" from the home directory on your server to a location on your windows box.

24. Print the file from your windows box. (The last steps are most useful if your windows box is located distant from your server).

25. Go back to your PuTTy window, clean up the mess you made and leave PuTTY:

# cd /usr

# rm -R experiment

# cd /

# rm blurb

# pw userdel anotheruser

# exit

# exit

26. If you need to restart your server from a distance (using PuTTY) use the reboot command (it will not attempt to shut down the power):

# reboot

27. Try out the power shutdown:

# shutdown -p +01:00

Collapse
Posted by Aernout Schmidt on
1. Two preliminary actions are further required: installing the right FreeBSD ports collection and installing the web-ftp tool called wget.

2. FreeBSD comes with access to a huge amount of ports, i.e. open source programs that are consistently packed with configuration- and compilation scripts (Makefiles) so they can be compiled and installed easily. The reason to write this documentation is mainly that these ports are frequently updated and that the conventions for locating libraries, object files etc. are constantly being adjusted. The result is, for instance, that the excellent OpenACS/FreeBSD installation guide at http://www.orchardlabs.com/library/freebsd/ leads to a few errors of the irritating file-not-found type if it is applied to the installation of newer software versions (like aolserver-3.4.2 and postgresql-7.2.1). Since this documentation will soon suffer the same deficit, I will give some hints on solving this type of problems where they may be expected.

3. In order to get access to the ports collection, one port has to be installed in a particular way. Its name is cvsup-without-gui (I use this, because I do not need Xwindows on my server). Since my server does not have (or need) a dedicated screen and keybourd, I assume you work from your client machine using PuTTy.

4. Get the cvsup binaries:

# ftp -a ftp.freebsd.org

ftp> cd /pub/FreeBSD/ports/i386/packages-stable/net

ftp> ls cvsup-without-gui*

Remember the version number of the cvsup-without-gui package

ftp> bin

ftp> get cvsup-without-gui-versionnumber.tgz

ftp> quit

5. Install the binaries:

# pkg_add cvsup-without-gui-versionnumber.tgz

# rehash

6. Prepare cvsup for downloading the ports collection:

# cd /usr/src/share/examples/cvsup/

# edit ports-supfile

In ports-supfile change the cvsup mirror to your nearest mirror. This is the line you need to change:

*default host=cvsup2.FreeBSD.org

For the Netherlands it becomes:

*default host=cvsup.nl.FreeBSD.org

Leave the editor - save the changes.

The ports-supfile controls cvsup's action. You may not find this file at the location metioned (I found its location changed in the currently experimental FreeBSD 5.0 nightly tarball). It is unlikely that the name of this file will change, however. So, if needed, a relatively safe line of action would be to search for the location of the ports-supfile using the find command and edit that file in its location as found. Also remember that the online documentation is often up-to-version (the change was documented in man cvsup).

7. Download the ports collection. The location, configuration and compilation information is brought to your machine, not the sources themselves. To download all of them took me about an hour:

# /usr/local/bin/cvsup -g -L 2 ports-supfile

8. Check de versions of the relevante ports - there are several ports collection versions.

# cd /usr/ports/www/aolserver

# cat distinfo

The version number of the aolserver port should be greater than or equal to 3.4.2

# cd /usr/ports/databases/postgresql7

# cat distinfo

The version number of the postgresql7 port should be greater than or equal to 7.2.1.

If not, you should upgrade your ports collection through editing the ports-supfile, based on the information in the man pages for cvsup.

9. Get, compile and install the wget port - you will use it to ftp files from web pages:

# cd /usr/ports/ftp/wget

# make install

We're all set for the next question.
Collapse
19: Simple acs4 site (response to 1)
Posted by Ben Koot on
Each subscriber to Timedesk will have his/her own blog (home) page. I will be using this to offer a simple way to get people using the other services I will be adding to TimeDesk. I would like to use the profile (since that's the part of personal information that is made public) as a mini website, with blog as a default package, available upon registration.

How do I associate a (blog)package to an individual user? where does the group and subsite structure fit in this scneario or is it irelevant? Thanks for your tips.I am sorry, but I still fail to see the structure, probly to much used to OpenACS 3.