Forum OpenACS Q&A: Re: Instant gratification OpenACS installation documentation needed
After reading Joel's post I had the thought that if we are going to work on a "Document" to create a basic install, then the document should really just be about creating a mobile tarball and installation script. What is needed to add to Joel's script is the correct users/groups for the installation. This could be packages into a single script, that might check a few things to make sure nothing is being overwritten.
Once this document is created, any of the guru's here should be able to create their newist install according to the doc and tar it up and provide it back to the community.
Eveyone here probably hates the amount of wasted time to install correctly all the junk we need. This is only compounded when there isn't a way to provide this work directly back to everyone else.
In other words, if the installation was done in big phases:
Someone could just do phase one, one way being a binary install which would be useable by most everyone.
I am new to the community and have been setting up OpenACS on Slackware for a couple days, and have been tinkering with various parts of the OpenACS system for a couple of weeks. This forum has been a God-send -- thank you all for sharing your knowledge and experience.
I agree very much that new OpenACS users would benefit from an easier point-of-entry.
The current installation documents are quite good, and I have been able to dig into the documentation for supporting packages where I have had trouble. In fact, I would say that the install docs, as they stand, are _much_better_ than usual for this kind of system. I have experienced very little of the extended frustrations that I have had on other occasions. The explanations are clear and give enough "big picture" information to help me understand where I'm going, and where to get answers when I need further information.
But still, the point-of-entry is too high for most people. My point of reference is Zope, which I have played with a bit, on both Windows and Linux. Under both operating systems, there is very little to do -- just install the system using the standard package-installation approach for that OS, and that's _it_. You end up with a working installation of the software in about 15 minutes, and you can begin to play with it. This is quite a contrast from the 15 hours or so that I have been working at getting OpenACS up and going -- though I'll grant that I'm doing everything, including OpenSSL and building PostgreSQL with Tcl and Python, and Qmail and Daemontools. I'll also say that, from what I've seen so far, OpenACS is much more of a production-level set of tools, and so one should expect more work to do. And too, I'm still learning UN*X, having come from a Windows world, so that's probably slowed me down some.
All of the kinds of things that you have been talking about would be useful to the new user.
(1) A clear document to describe how to make a "basic play/test/development installation" from the available software packages.
(2) A document to describe how to upgrade a basic installation to a production installation. One of the reasons that I am doing everything I can now is, I don't have the experience to know how difficult it would be to add these things in later, and so I'm doing it now. If there were a document that described the paths to upgrade, though, I would have more confidence doing a simple installation now. (Some of the discussion on this thread suggests to me that, in fact, the "full install" is a good idea because the upgrade path is not straightforward.)
(3) Pre-compiled binaries for a variety of systems. This would significantly speed up the installation process and lower the bar for new users. Most of this software compiles very easily (though I've had a little trouble today getting nsopenssl to recognize that I built openssl with threads ... but I'll get through that; and I could probably come back to that later on). But the time involved in doing all of the compiling is not trivial. I previously built a simple but dynamic, working Zope site from scratch in less time than I have spent waiting for gcc to run, which includes the time I spent reading "The Zope Book."
(A side note: I spent/wasted a lot of time trying to set things up under Windows, only to discover that I needed MSVC++ to build AOLserver -- it wouldn't build with DJGPP, at least on my system (WinXP Pro). I was unable to find a binary of AOLserver for Windows, either on the the Sourceforge site or on the EmpoweringMinds site. Has an AOLserver binary for Windows been posted publically?)
(A second side note: Even though the installation docs are fine, there seems a dearth of books on AOLserver and OpenACS. When I go to Borders and see the piles of PHP and MySQL and Apache books, it's a little disconcerting to have chosen Tcl/PostgreSQL/AOLserver. I know what I'm after, and I've taken the time to study the differences; so I feel confident I've made the right choice. But I like books -- and I think it would give many people more confidence if they could see O'Reilly publications -- or any printed books at all -- on AOLserver and OpenACS. I was glad to see, though, a book on PostgreSQL. It would be very encouraging to new users to see links on the OpenACS site to "The OpenACS Book" or whatever its title will be.)
(4) Full binary installation packages for a number of OSes would be extremely useful. I am currently working with Slackware, so if I get to the point where everything is working satisfactorily I would be interested in working on a Slackware package. I realize that shared libraries make this process non-trivial. But others have succeeded with equally complex software. It is something to work toward. RedHat, Debian, OpenBSD, and Windows should have pre-compiled binaries among their offerings. A Windows install-package would not be significantly bigger than that of other large software packages, and would make it possible for a lot more people to install "play" versions OpenACS on their Windows laptops and workstations.
(5) Someone mentioned documentation that begins where installation leaves off, to help those new to the system to get familiar with it and how to make use of it to build dynamic site and community services. This would be outstanding. Though I have not yet reached the "congratulations" screen, I suppose I'll be there in the next couple of hours of work. I know I would benefit from and appreciate some general guidance at that point.
If easy-to-install packages were available, then a lot more people would get to the point of being able to make use of such documents, And, such documents would themselves be one of the better advertisements for OpenACS versus PHP & friends.
Those are some thoughts from the perspective of a beginner. I am also willing to contribute in whatever way I can to a documentation effort.
Shawn Harrison
The very minute you start customizing any OpenACS files, you must at least know and record exactly what OpenACS version you installed and where you got it from. Hopefully, just keeping the original tarball around should answer that question for you, as long as the OpenACS version (and corresponding CVS tag!) is properly documented in the tarball. Doing a cvs import (onto a vendor branch) of the sources is an ideal way to do this, but can be skipped at this point if you wish. As long as you know what you started with.
Once you've both modified any OpenACS files (which at least currently basically means, "for all Production sites") and want to now upgrade OpenACS, you have to put everything under CVS.
(As an aside: This really shouldn't be a problem, because frankly, if you're creating a production site using the toolkit then you're a programmer, and if you're a programmer you or at least one member of your team needs a firm grasp of CVS.)
So, now that you want to upgrade, either you cvs imported OpenACS right when you started, or you waited till now. If you waited till now, what you do is go back to your original tarball, cvs import that, create your CVS checkout of just the stock stuff from the tarball, then copy all your non-CVS stuff on top of that checkout. Then commit all your changes. Now you're at the same place as if you cvs imported way back when you first started using OpenACS. It's a bit easier to do that CVS stuff at the beginning rather than after the fact, but it's doable either way.
I think ignoring the above rules of thumb are the only ways you're really likely to shoot yourself in the foot by postponing "Production ready" infrastructure work till later. E.g., if you don't know what version you installed, customized and then upgraded various pieces without any version control - that sort of thing will definitely cause you extra work.
Oh, one more way - custom data model changes. That can be kind of like CVS snafus except worse. But people aren't likely to get into that at all unless they already have a pretty good idea of what they're doing.
But stuff like using pre-compiled binaries vs. compiling your own, using inittab rather than daemontools, etc., none of that is going to cause you extra work later, even if you decide you later want to switch. In fact, it may well save you time, and you may be happy with it for years.
Oh, and we probably have somewhere in big bold letters: "If you are new to OpenACS, do not try to do any of this on Windows. It can be run on Windows, and if you are an OpenACS expert, go right ahead, but 95% of OpenACS users use Linux not Windows, so if you're a beginner you should use Linux too."
So that's three so far: Things to be careful about when thinking about taking a shortcut: Version control, Linux vs. Windows (Windows is not a shortcut - unless you're talking John Sequeira's OpenACS on Linux in VMware on Windows thing), and less commonly, data model modifications.
Thanks for your response and for giving me those suggestions and guidance. All of what you said was very helpful. Last night I got to the "Congratulations!" screen, 😊 and then stayed up too late looking around the out-of-the-box site package. Feeling the freedom to let some things be not-quite-resolved -- such as putting AOLserver in daemontools and getting qmail and nsopenssl fully working -- was helpful to me, so that I didn't get bogged down but pressed ahead.
Since CVS is an important element of a production site, and since you can shoot yourself in the foot, as you say, by not including it, I would suggest that having the "quick install" use CVS should be the default, installing CVS on the system if it's not already there. Since the other things can all be added later, it would be simpler (less daunting) for the new folks not to have to wade through those things in the initial install document.
Speaking of the out-of-the-box package, it is really very impressive. Lars mentioned that, currently, many people might not get to that point and turn away before seeing it. That, when it happens, is really unfortunate, because what you get out-of-the-box is so much more than what you get with other, similar packages -- more professional, more "industrial strength," and more transparent. Having such a powerful system as this be so transparent in its architecture is almost unnerving, as compared for instance with Zope which (in my experience) seems to obfuscate the simple. If people would have the opportunity to see what OpenACS is all about, I think it would really take off in its popularity. There are a lot of people willing to spend an hour to find out, but not ten hours. If a couple of journalists were to spend that hour and have good results, no doubt some buzz would begin to build.
More thoughts from a beginner,
Shawn Harrison
There are Windows binaries of AOLserver 4.0 beta 8 available at http://empoweringminds.mle.ie/openacs/4/ Starting from my distribution and documentation is a *much* easier way to install OpenACS on Windows than starting from the AOLserver sources. I haven't been publicizing the beta build's existence because I don't really have time to support it, but once AOLserver 4.0 is final, the Windows binaries and installer will be available on SourceForge.
Native Win32 PostgreSQL is due with 7.4 - it has been held up but might be out at the end of the summer. I'm hoping it will have a nice installer like the one for pgAdmin II. So with a little more time and work, Windows will be a first class platform for OpenACS, but as Andy suggested, we should probably put up a warning in the meantime.
