Re: [Zope-dev] [Zope-Checkins] SVN: Zope/branches/tseaver-clarify_install_docs/doc/ Split out docs for 'normal' installation from those using 'zc.buildout'.
Tres Seaver wrote:
Installing Zope -=============== +---------------
-Unless using buildout to build a zope instance as described -:ref:`below <buildout-instances>`, you will need to install Zope -separately. If you want to create a buildout-based Zope instance, -please skip directly to that section. +The recommended way to install Zope is within a virtualized Python environment +using ``virtualenv`` as follows::
Really? I wouldn't recommend virtualenv... Myself, I find the buildout instance the easiest and lightest weight method... By all means, document virtualenv as an option, but blessing it as "the one true way" is a bit much... cheers, Chris -- Simplistix - Content Management, Batch Processing & Python Consulting - http://www.simplistix.co.uk
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Chris Withers wrote:
Tres Seaver wrote:
Installing Zope -=============== +---------------
-Unless using buildout to build a zope instance as described -:ref:`below <buildout-instances>`, you will need to install Zope -separately. If you want to create a buildout-based Zope instance, -please skip directly to that section. +The recommended way to install Zope is within a virtualized Python environment +using ``virtualenv`` as follows::
Really? I wouldn't recommend virtualenv... Myself, I find the buildout instance the easiest and lightest weight method...
By all means, document virtualenv as an option, but blessing it as "the one true way" is a bit much...
Here's my rationale: - - The docs are intended primarily for folks who want to install and run Zope, rather than hack on it. - - zc.buildout is *super* heavyweight compared to virtualenv - - zc.buildout creates an environment which is puzzling as hell for anybody who hasn't already drunk the koolaid ('parts'? 'eggs'? WTF?) - - virtualenv, or something damn near it, is likely to land in Python itself. - - Nearly anybody else in the Python world is more likely to be familiar with the virtualenv stuff than with buildout. - - We have two alternate zc.buildout scenarios (install Zope + run mkzopeinstance vs. self-contained environment). The first has no real advantage over the virtualenv one, except being able to run buildout to update the software (heaven help you if you forget to configure the index properly!). The second leaves you without the annotated config file, a *major* faux pas. I plan to merge that branch to the 2.12 branch and the trunk, assuming no further objections. Tres. - -- =================================================================== Tres Seaver +1 540-429-0999 tseaver@palladion.com Palladion Software "Excellence by Design" http://palladion.com -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iEYEARECAAYFAkuNTyUACgkQ+gerLs4ltQ7i/wCfeWwoIe1pqmjAgtOlKbb7km7O xyUAnjgyYNcaz3qIIMB9ZKMn1F+NBcha =CRlO -----END PGP SIGNATURE-----
Tres Seaver wrote:
- - The docs are intended primarily for folks who want to install and run Zope, rather than hack on it.
Says who? The last comment I had on those docs was from Marius when he had to go back to a Zope 2 project and wanted to make it buildout based. I've also used those docs myself when doing upgrades to Zope 2.12 (one of the reasons I did all the work on them!)
- - zc.buildout is *super* heavyweight compared to virtualenv
A point of view, I don't happeen to agree, especially for the simple case of an instance... virtualenv doesn't fit my brain, buildout does. I'd hazard a guess that people still interested in Zope 2 might fall into that category too...
- - zc.buildout creates an environment which is puzzling as hell for anybody who hasn't already drunk the koolaid ('parts'? 'eggs'? WTF?)
...or not. bin/zopectl ...which is what you've done in Zope instances for years now... having to guess where to find zopectl in a virtual env is not something that comes naturally to all of us...
- - virtualenv, or something damn near it, is likely to land in Python itself.
I don't think that discussion is anywhere near done yet ;-)
- - Nearly anybody else in the Python world is more likely to be familiar with the virtualenv stuff than with buildout.
Not 100% on that either, buildout has been active service in the Django community, and for all I know, elsewhere too..
- - We have two alternate zc.buildout scenarios (install Zope + run mkzopeinstance vs. self-contained environment).
Yes, I'm much more for the latter, but when I tried to make that "the only way", someone whined, so I tried to stay neutral...
run buildout to update the software (heaven help you if you forget to configure the index properly!).
How is that any different from the virtual env route?!
The second leaves you without the annotated config file, a *major* faux pas.
If someone wants to knock up a paster template, go right ahead. Myself, I'm not that fussed. I always trim away all the default values and commentary from my zope.conf anyway, since I know where to find the skeleton (wouldn't it be great if that figured in the Zope 2 docs where it belongs, since it really is documentation) and I like short config files that say what *is* actually configured rather than what *might* be a default value...
I plan to merge that branch to the 2.12 branch and the trunk, assuming no further objections.
Well, maybe wait to see what other people think. The above is obviously my personal view, but I'd be surprised if I was the only person who had that view... Chris -- Simplistix - Content Management, Batch Processing & Python Consulting - http://www.simplistix.co.uk
On Tue, Mar 02, 2010 at 06:12:30PM +0000, Chris Withers wrote:
Tres Seaver wrote:
- - The docs are intended primarily for folks who want to install and run Zope, rather than hack on it.
Says who? The last comment I had on those docs was from Marius when he had to go back to a Zope 2 project and wanted to make it buildout based.
I wanted to upgrade Zope 2 on a local non-profit's server. I found the INSTALL document. It gave me many options, which was confusing. I picked the buildout option since I thought it was the one blessed by the Zope community. I went through some paint getting it to work, and I consider myself to be pretty familiar with buildout. In retrospect I think I should've used virtualenv + mkzopeinstance. I'm +10 for having a single recommended install option documented in INSTALL.txt. Let the other options be relegated to appendices in a separate file, for people who think they want buildout/rpm/whatever. I don't much care if that option is buildout or virtualenv or anything else, as long as it is reasonably simple and works well for most users. Currently I'm feeling +0.9 towards virtualenv over buildout, but this feeling slowly oscillates over time. A while ago I preferred buildout over virtualenv; now I just need to experience a certain number of virtualenv bugs and issues to swing me back. ;-)
- - zc.buildout is *super* heavyweight compared to virtualenv
A point of view, I don't happeen to agree, especially for the simple case of an instance... virtualenv doesn't fit my brain, buildout does.
That is a curious observation. I find it much easier to understand what virtualenv does and how it does it: the underlying model is simpler. Of course it has fewer features than buildout, which is why I use buildout for *development*, but I've seen the cost of those features in increased complexity and difficulty of debugging when something goes wrong. Actually, now that I think about it more, a buildout would have one advantage over virtualenv: with a fixed versions.cfg your Zope 2 installs won't start failing when somebody uploads a new-improved-and-incompatible version of zope.component into PyPI.
- - We have two alternate zc.buildout scenarios (install Zope + run mkzopeinstance vs. self-contained environment).
Yes, I'm much more for the latter, but when I tried to make that "the only way", someone whined, so I tried to stay neutral...
There will always be people who whine :( Marius Gedminas -- http://pov.lt/ -- Zope 3 consulting and development
Marius Gedminas wrote:
That is a curious observation. I find it much easier to understand what virtualenv does and how it does it: the underlying model is simpler.
How do I go from a checkout to a working system in virtualenv? How do I lock down to particular versions with virtualenv? Maybe that's the missing link for me... can you help me?
Actually, now that I think about it more, a buildout would have one advantage over virtualenv: with a fixed versions.cfg your Zope 2 installs won't start failing when somebody uploads a new-improved-and-incompatible version of zope.component into PyPI.
Right. This is a pretty crucial thing when it comes to Zope 2 and it's veritable constellation of eggs...
Yes, I'm much more for the latter, but when I tried to make that "the only way", someone whined, so I tried to stay neutral...
There will always be people who whine :(
Yes, but Yuppie whines even louder than I do... Chris -- Simplistix - Content Management, Batch Processing & Python Consulting - http://www.simplistix.co.uk
Hi Tres! Tres Seaver wrote:
Chris Withers wrote:
By all means, document virtualenv as an option, but blessing it as "the one true way" is a bit much...
I'm also surprised that you propose to make this *the* recommended way.
Here's my rationale:
- - The docs are intended primarily for folks who want to install and run Zope, rather than hack on it.
So you recommend virtualenv for administrators and buildout for developers? Or where do you draw the line? And when do you recommend to switch from one setup to the other? Or do you always recommend virtualenv? I thought zc.buildout is preferred by most people in the Zope community.
- - zc.buildout is *super* heavyweight compared to virtualenv
- - zc.buildout creates an environment which is puzzling as hell for anybody who hasn't already drunk the koolaid ('parts'? 'eggs'? WTF?)
virtualenv is also puzzling if you are not familiar with it. Using activate and deactivate or the right paths isn't much easier to learn than using zc.buildout.
- - virtualenv, or something damn near it, is likely to land in Python itself.
- - Nearly anybody else in the Python world is more likely to be familiar with the virtualenv stuff than with buildout.
But not everybody in the Python world is familiar with virtualenv. Why should we encourage people to make themselves familiar with virtualenv instead of zc.buildout?
- - We have two alternate zc.buildout scenarios (install Zope + run mkzopeinstance vs. self-contained environment). The first has no real advantage over the virtualenv one, except being able to run buildout to update the software (heaven help you if you forget to configure the index properly!). The second leaves you without the annotated config file, a *major* faux pas.
I consider the self-contained scenario still as experimental. Following the instructions requires much more typing than the other scenarios. But I'm optimistic it can and will be improved. Cheers, Yuppie
yuppie wrote:
I consider the self-contained scenario still as experimental.
You might, I don't. I've deployed this happily in production with a few customer now. Just because you don't happen to like it yourself, please don't belittle it... Chris -- Simplistix - Content Management, Batch Processing & Python Consulting - http://www.simplistix.co.uk
Hi Chris! Chris Withers wrote:
yuppie wrote:
I consider the self-contained scenario still as experimental.
You might, I don't. I've deployed this happily in production with a few customer now.
Just because you don't happen to like it yourself, please don't belittle it...
I didn't mean to belittle it. 'experimental' is nothing negative. I'm happy people like you are working on and with this approach. But IMHO some details like the role of the annotated config file or if a paster template would make things easier are not yet fleshed out enough to make it *the* recommended scenario. Cheers, Yuppie
yuppie wrote:
Hi Chris!
Chris Withers wrote:
yuppie wrote:
I consider the self-contained scenario still as experimental. You might, I don't. I've deployed this happily in production with a few customer now.
Just because you don't happen to like it yourself, please don't belittle it...
I didn't mean to belittle it. 'experimental' is nothing negative. I'm happy people like you are working on and with this approach.
There's no "working on", it's done, dusted and in production...
But IMHO some details like the role of the annotated config file or if a paster template would make things easier are not yet fleshed out enough to make it *the* recommended scenario.
Bull. It's fine as it is, this 'death by feature request' is rediculous... Chris -- Simplistix - Content Management, Batch Processing & Python Consulting - http://www.simplistix.co.uk
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 yuppie wrote:
Tres Seaver wrote:
Chris Withers wrote:
By all means, document virtualenv as an option, but blessing it as "the one true way" is a bit much...
I'm also surprised that you propose to make this *the* recommended way.
Here's my rationale:
- - The docs are intended primarily for folks who want to install and run Zope, rather than hack on it.
So you recommend virtualenv for administrators and buildout for developers? Or where do you draw the line? And when do you recommend to switch from one setup to the other? Or do you always recommend virtualenv?
I recommend virtualenv to anybody who just wants to install and run the Zope2 appserver, without needing to drink a lot of "kool-aid": just install it from PyPI, run 'mkzopeinstance', and you're done. Note that I specifically remomve the non-virtualenv easy_install docs: I don't want us *ever* to encourage the use of easy_install outside a virtualenv.
I thought zc.buildout is preferred by most people in the Zope community.
buildout works for *developers*: it is completely strange for people who just want to install and run Zope. Mixing the buildout version of the installation in with the non-buildout version was a disaster, from a readability standpoint.
- - zc.buildout is *super* heavyweight compared to virtualenv
- - zc.buildout creates an environment which is puzzling as hell for anybody who hasn't already drunk the koolaid ('parts'? 'eggs'? WTF?)
virtualenv is also puzzling if you are not familiar with it. Using activate and deactivate or the right paths isn't much easier to learn than using zc.buildout.
The environment itself is much closer to what people expect: libraries installed under 'lib/pythonX.Y', scripts in 'bin', headers in 'include', no funky 'parts' or 'eggs' directories, no idea that config files might get blown away just because you update software. I know that some of that is due to popular recipes, but that argument is specious: buildout's value proposition derives in part from the network effect of having those recipes available and widely used. Activate is a completely unnecessary attractive nuisacne: I *never* use it, and I routinely see people who *do* use it end up running from different environments than the ones they think they are running.
- - virtualenv, or something damn near it, is likely to land in Python itself.
- - Nearly anybody else in the Python world is more likely to be familiar with the virtualenv stuff than with buildout.
But not everybody in the Python world is familiar with virtualenv. Why should we encourage people to make themselves familiar with virtualenv instead of zc.buildout?
I would bet that, outside the Zope community, virtualenv's mindshare is ten times that of buildout. Adding it to the stdlib was actually a topic on the agenda of the pre-PyCon language summit, for instance.
- - We have two alternate zc.buildout scenarios (install Zope + run mkzopeinstance vs. self-contained environment). The first has no real advantage over the virtualenv one, except being able to run buildout to update the software (heaven help you if you forget to configure the index properly!). The second leaves you without the annotated config file, a *major* faux pas.
I consider the self-contained scenario still as experimental. Following the instructions requires much more typing than the other scenarios. But I'm optimistic it can and will be improved.
The self-contained mode is likely *perfect* for developers who produce a highly-customized bundle o Zope, 3rd party software, and custom code. It just isn't right as the "first choice" for somebody installing Zope for the first time. Tres. - -- =================================================================== Tres Seaver +1 540-429-0999 tseaver@palladion.com Palladion Software "Excellence by Design" http://palladion.com -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iEYEARECAAYFAkuOxiAACgkQ+gerLs4ltQ4UhwCgyb5BGFZD1Lz/9rYLng10ekx8 sk4An2pmynQ8PUZagq1CAbd6+tasXyIj =B00w -----END PGP SIGNATURE-----
On 03/03/2010 09:27 PM, Tres Seaver wrote:
The self-contained mode is likely *perfect* for developers who produce a highly-customized bundle o Zope, 3rd party software, and custom code. It just isn't right as the "first choice" for somebody installing Zope for the first time.
I never considered anybody except developers doing "straight" installations of Zope itself. I usually expect developers/admins/devops to deploy an actual application/project which usually has some more expectations on environment and installed components than just a Zope server. In that case I expect a "project description" which will contain complete installation instructions readable by man and machine and can be used by both developers and admins. The cool-aid part is a bit troublesome to me in the sense that a plain Zope server won't stay plain for long. Using lots of additional packages without a tool that allows you to keep track of what you installed and configured (so that this information can go to version control) will put people in a horrible place quickly. I have the feeling that experience will then fall back to Zope again because people say "you can't manage that complexity" whereas we have a tool for that but we decided it not to be built into Zope itself. Christian -- Christian Theune · ct@gocept.com gocept gmbh & co. kg · forsterstraße 29 · 06112 halle (saale) · germany http://gocept.com · tel +49 345 1229889 0 · fax +49 345 1229889 1 Zope and Plone consulting and development
Hi Tres! Tres Seaver wrote:
I recommend virtualenv to anybody who just wants to install and run the Zope2 appserver, without needing to drink a lot of "kool-aid": just install it from PyPI, run 'mkzopeinstance', and you're done.
Who are these people? Why do they want to install and run Zope2? Is Zope2 in any way useful for non-developers? Is pure TTW development the best way to get started? Or do you recommend virtualenv as well for small file-system based projects? Cheers, Yuppie
Am 03.03.2010, 21:27 Uhr, schrieb Tres Seaver <tseaver@palladion.com>:
I recommend virtualenv to anybody who just wants to install and run the Zope2 appserver, without needing to drink a lot of "kool-aid": just install it from PyPI, run 'mkzopeinstance', and you're done. Note that I specifically remomve the non-virtualenv easy_install docs: I don't want us *ever* to encourage the use of easy_install outside a virtualenv.
Thanks for the clarification.
I thought zc.buildout is preferred by most people in the Zope community. buildout works for *developers*: it is completely strange for people who just want to install and run Zope. Mixing the buildout version of the installation in with the non-buildout version was a disaster, from a readability standpoint.
I'm not sure if take up outside the Zope community is that important. I've not come across virtualenv in a non-Zope context but then I don't spend a lot of time trying out all the "cool" software out there. What is important is that people can get up and running easily and don't f*ck their systems with injudicious use of setuptools magic. The important thing, as I see it, is: "In the face of ambiguity, refuse the temptation to guess. There should be one-- and preferably only one --obvious way to do it." In my view neither virtualenv nor buildout are quite there. If someone can explain to me how to use virtualenv in a way that makes it easy to deploy what I've developed on another environment then I'd be happy to go that way.
virtualenv is also puzzling if you are not familiar with it. Using activate and deactivate or the right paths isn't much easier to learn than using zc.buildout.
The environment itself is much closer to what people expect: libraries installed under 'lib/pythonX.Y', scripts in 'bin', headers in 'include', no funky 'parts' or 'eggs' directories, no idea that config files might get blown away just because you update software. I know that some of that is due to popular recipes, but that argument is specious: buildout's value proposition derives in part from the network effect of having those recipes available and widely used.
The layout of a buildout project is indeed somewhat confusing. But the config file makes it much easier to replicate what you're doing elsewhere and I think most Zope users will be developing something locally to run elsewhere, in which case it should be made as easy as possible to replicate the experience. The only install & run users I can think of would be Plonies and they have their unified installers anyway.
Activate is a completely unnecessary attractive nuisacne: I *never* use it, and I routinely see people who *do* use it end up running from different environments than the ones they think they are running.
+10 I thought I'd been dumped into a new shell / interactive Python the first time I saw it!
- - We have two alternate zc.buildout scenarios (install Zope + run mkzopeinstance vs. self-contained environment). The first has no real advantage over the virtualenv one, except being able to run buildout to update the software (heaven help you if you forget to configure the index properly!). The second leaves you without the annotated config file, a *major* faux pas.
I consider the self-contained scenario still as experimental. Following the instructions requires much more typing than the other scenarios. But I'm optimistic it can and will be improved. The self-contained mode is likely *perfect* for developers who produce a highly-customized bundle o Zope, 3rd party software, and custom code. It just isn't right as the "first choice" for somebody installing Zope for the first time.
Who is likely to be installing Zope for the first time? Much as I love Zope, we have to acknowledge that as things stand Zope is not attractive for newbies. But this is not just about getting up and running. Charlie -- Charlie Clark Managing Director Clark Consulting & Research German Office Helmholtzstr. 20 Düsseldorf D- 40215 Tel: +49-211-600-3657 Mobile: +49-178-782-6226
Tres Seaver wrote:
I recommend virtualenv to anybody who just wants to install and run the Zope2 appserver, without needing to drink a lot of "kool-aid":
How do you get them using the set of eggs specified in the appropriate versions.cfg using this recommendation?
Activate is a completely unnecessary attractive nuisacne: I *never* use it, and I routinely see people who *do* use it end up running from different environments than the ones they think they are running.
Right, so how do I avoid it? Is that in your new Zope 2 docs?
The self-contained mode is likely *perfect* for developers who produce a highly-customized bundle o Zope, 3rd party software, and custom code. It just isn't right as the "first choice" for somebody installing Zope for the first time.
I fail to see why not. It's a simple 2 step recipe for them: - checkout - run buildout I was even going to wrap this up into a zope2instance.py script, but I ran out of time... Chris -- Simplistix - Content Management, Batch Processing & Python Consulting - http://www.simplistix.co.uk
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Chris Withers wrote:
Tres Seaver wrote:
I recommend virtualenv to anybody who just wants to install and run the Zope2 appserver, without needing to drink a lot of "kool-aid":
How do you get them using the set of eggs specified in the appropriate versions.cfg using this recommendation?
You install from the index built from that same set of known good versions: $ /path/to/virtualenv --no-site-packages /tmp/z2123 $ /tmp/z2123/bin/easy_install \ -i http://download.zope.org/Zope2/index/2.12.3/ Zope2 $ /tmp/z2123/bin/mkzopeinstance -d /tmp/instance -u admin:123 $ /tmp/instance/bin/zopectl fg
Activate is a completely unnecessary attractive nuisacne: I *never* use it, and I routinely see people who *do* use it end up running from different environments than the ones they think they are running.
Right, so how do I avoid it? Is that in your new Zope 2 docs?
You just use the scripts in the 'bin' directory, as above. Sourcing 'activate' pollutes your shell's environment for the dubious benefit of saving a couple of keystrokes.
The self-contained mode is likely *perfect* for developers who produce a highly-customized bundle o Zope, 3rd party software, and custom code. It just isn't right as the "first choice" for somebody installing Zope for the first time.
I fail to see why not. It's a simple 2 step recipe for them:
- checkout - run buildout
Checkiog Zope out from SVN is not part of an appropriate installation model for folks who are not interested in hackin on Zope itself. Tres. - -- =================================================================== Tres Seaver +1 540-429-0999 tseaver@palladion.com Palladion Software "Excellence by Design" http://palladion.com -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iEYEARECAAYFAkuZCRQACgkQ+gerLs4ltQ6qjQCdH0QLW73sU2XKufa2oThHtzqw KxIAniIKtGyuc7svGfP/LiHF2NRsnyVV =8hwt -----END PGP SIGNATURE-----
Tres Seaver wrote:
I recommend virtualenv to anybody who just wants to install and run the Zope2 appserver, without needing to drink a lot of "kool-aid": How do you get them using the set of eggs specified in the appropriate versions.cfg using this recommendation?
You install from the index built from that same set of known good versions:
$ /path/to/virtualenv --no-site-packages /tmp/z2123 $ /tmp/z2123/bin/easy_install \ -i http://download.zope.org/Zope2/index/2.12.3/ Zope2 $ /tmp/z2123/bin/mkzopeinstance -d /tmp/instance -u admin:123 $ /tmp/instance/bin/zopectl fg
Right, and how how do I get my own packages into the mix, with specific, locked versions, in an easily reproducible fashion?
The self-contained mode is likely *perfect* for developers who produce a highly-customized bundle o Zope, 3rd party software, and custom code. It just isn't right as the "first choice" for somebody installing Zope for the first time. I fail to see why not. It's a simple 2 step recipe for them:
- checkout - run buildout
Checkiog Zope out from SVN is not part of an appropriate installation model for folks who are not interested in hackin on Zope itself.
Meh, by checkout, I really meant "write a buildout.cfg and put it in en empty directory with a copy of bootstrap.py". There's no need to check anything of svn, the eggs on PyPI are just fine... Chris -- Simplistix - Content Management, Batch Processing & Python Consulting - http://www.simplistix.co.uk
participants (6)
-
Charlie Clark -
Chris Withers -
Christian Theune -
Marius Gedminas -
Tres Seaver -
yuppie