Forum OpenACS Q&A: Newbee documentation
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.
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:
- more than 1 person may answer with more than one perspective on the topic
- there is a greater chance that someone will be inspired to write an eloquent explanation which can then be incorporated into the documentation
- 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: http://openacs.org/contribute (and keep me posted, with any notes you have, also: email@example.com ).
For DotLRN, you should probably inquire in the dotLRN forum on who to contact: http://openacs.org/bboard/q-and-a.tcl?topic_id=15&topic=dotLRN%20Development
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 http://openacs.org/doc/openacs/ 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 http://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 http://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 http://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: http://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=0005nN&topic_id=11&topic=OpenACS http://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=0004ei&topic_id=11&topic=OpenACS http://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: http://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.
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.
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
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:
- read about the system in general
- install the system
- read more about the system via the installed and working system
- 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" ( http://openacs.org/doc/index-3.html ) from http://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.
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.
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: http://openacs.org/doc/openacs-4/acs-dev.html
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.
# script2. Make (as root user) a new directory
# mkdir -p /usr/experiment/testCheck
# man mkdirfor 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):
# pwd4. Change to the /usr/experiment/test directory:
# cd /usr/experiment/test5. Edit the file blurb in that directory (it will be a new file):
# edit blurb6. 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 /blurb8. 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 /blurb11. Make the new user "anotheruser" and give her a password:
# pw useradd -G wheel -d /home -n anotheruser
# passwd anotheruser12. Make "anotheruser" owner of /blurb
# chown -R anotheruser /blurb13. 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 - anotheruser15. 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):
$ pwd17. Become the root user again:
$ exit18. Stop logging your actions (Ctrl-c interrupts the active logging process started from the PuTTY console earlier):
# Ctrl-c19. 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" -print20. 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
# exit26. 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):
# reboot27. Try out the power shutdown:
# shutdown -p +01:00
# 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> quit5. Install the binaries:
# pkg_add cvsup-without-gui-versionnumber.tgz # rehash6. Prepare cvsup for downloading the ports collection:
# cd /usr/src/share/examples/cvsup/ # edit ports-supfileIn ports-supfile change the cvsup mirror to your nearest mirror. This is the line you need to change:
*default host=cvsup2.FreeBSD.orgFor the Netherlands it becomes:
*default host=cvsup.nl.FreeBSD.orgLeave 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-supfile8. Check de versions of the relevante ports - there are several ports collection versions.
# cd /usr/ports/www/aolserver # cat distinfoThe version number of the aolserver port should be greater than or equal to 3.4.2
# cd /usr/ports/databases/postgresql7 # cat distinfoThe 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 installWe're all set for the next question.
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.