Forum OpenACS Q&A: Re: Instant gratification OpenACS installation documentation needed
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,