Poor installation user experience

[M.-A. Lemburg]

I think that the installation part of the user experience needs to be revisited:

<user-story>

A user wants to install Zope2 using buildout...

She goes to http://www.zope.org/, then sees the note regarding the new website, clicks on the link, goes to http://zope2.zope.org/

She then clicks on the release news item http://zope2.zope.org/news/zope-2.13.0-released, finds the notes on the release, but no download or installation information.

She then searches the site and finds the "Getting Zope 2" link at the top, clicks on it and goes to http://zope2.zope.org/releases

She reads the installation instructions, clicks on the link and gets directed to http://docs.zope.org/zope2/releases/2.12/INSTALL.html

After some research, she finds that the page points to Zope 2.12 and not 2.13, so she goes back and clicks on the http://docs.zope.org/ link. This takes her to a documentation overview, but there is no sign of installation instructions, so she goes back to the 2.12 installation instructions.

After some more research, she finds a link "Zope Release Information" and goes to http://docs.zope.org/zope2/releases/index.html

On that page, she finds the Zope 2.13 links to "Installing and Zope with zc.buildout" (sic !), clicks on it a finally arrives at the page http://docs.zope.org/zope2/releases/2.13/INSTALL-buildout.html

She then follows instructions and hits the first bummer:

wget http://pypi.python.org/packages/source/Z/Zope2/Zope2-<Zope version>.tar.gz

No .tar.gz is available. Looking at http://pypi.python.org/packages/source/Z/Zope2/ she finds that there's a ZIP file, so downloads that and unzips it.

Continuing with the instructions she tries to bootstrap the installation:

/path/to/your/python bootstrap/bootstrap.py

bin/python: can't open file 'bootstrap/bootstrap.py': [Errno 2] No such file or directory

Looking at the directory, she sees that there's a bootstrap.py in the root dir of the distribution (not in a bootstrap/ subdir).

She runs that and then continues with bin/buildout.

This generates a few warnings which she ignores.

To her surprise, buildout then goes on to download a huge number of package eggs, even though she installed from a ZIP file (which she expected to already contain copies of all of these).

After getting coffee, she finally sees the script complete.

She then follows instructions, runs bin/mkzopeinstance, enters instance1 as dir and the admin user details.

Finally, she starts Zope using instance1/bin/zopectl start

.
daemon process started, pid=9760

Hmm, no mention of the site URL. So she looks in instance1/etc/zope.conf and finds that the standard location hasn't changed in the new release.

Pointing a brower at http://127.0.0.1:8080/ gives her the ZMI as expected.

</user-story>

There are a couple of things that would greatly improve the user experience:

 * the release news should include a link to the (correct) installation instructions
 * the download page should point to the installation instructions for each release version (since these vary per version), not only the change logs
 * the installation instructions should be updated to what's actually available on the download server
 * the buildout instructions need to be updated to what's actually in the ZIP archive
 * it would help, if the installation instructions included a hint on how to quickly fire up Zope for a test (it's not obvious that clicking "next" on the page will get you to those instructions and new users won't read the "Creating a buildout-based Zope instance", since they already followed the instructions on "Creating a Zope instance")

[Hanno Schlichting (hannosch)]

The install experience could certainly use some help.

[Andreas Jung (ajung)]

There is perhaps _little_ help available soon. www.zope.org is subject to be relaunched soon...most of the www.zope.org
cruft should have gone. Instead people interested in Zope 2 should find their exit to

https://zope2.zope.org/

There is a dedicated "Getting Zope" tab....there is already a list of download links and links to the installation docs.
Of course there is place for improvements :)

[Charlie_X (charlie)]

After discussions with MAL I've agreed to work on this.

Is mkzopeinstance still usable? I got an error that manuel was missing when I tried it.

I suggest offering a buildout only based install - a minimal configuration of about 30 lines seems all that is required.

[Charlie_X (charlie)]

What's the checkout for this?

[Hanno Schlichting (hannosch)]

We have instructions for installation via buildout at http://docs.zope.org/zope2/releases/2.13/INSTALL-buildout.html both using mkzopeinstance and using just a buildout config with simple config files. What part of this doesn't work?

The docs are all part of Zope2, for example at svn+ssh://svn.zope.org/repos/main/Zope/trunk/doc/INSTALL-buildout.rst

[Charlie_X (charlie)]

First of all, Zope 2.13 and up no longer use .tar.gz so we need .zip and unzip. Yesterday I had a failure with manuel but that must have been transitory

Secondly it is confusing to me, at least, to have both an install that uses buildout and and a separate buildout based one. I would suggest separate buildout configurations (if required) so that

virtualenv --no-site-packages zope-2.13.6
cd zope-2.13.6
either
wget path/to/bootstrap.py
or preferably
bin/pip install zc.buildout
wget path/to/sample/buildout.cfg
bin/buildout

[Charlie_X (charlie)]

Sample instance.cfg. This would simplify the install for someone just trying Zope out. The current buildout.cfg could be renamed to develop.cfg because it is really suited to developers. Shouldn't the WSGI part have it's own configuration?

virtualenv --no-site-packages my_zope
cd my_zope
wget http://svn.zope.org/*checkout*/Zope/tags/2.13.6/bootstrap.py
bin/python bootstrap.py
wget http://svn.zope.org/*checkout*/Zope/tags/2.13.6/versions.cfg
wget http://svn.zope.org/*checkout*/Zope/tags/2.13.6/instance.cfg
bin/buildout -c instance.cfg

[Hanno Schlichting (hannosch)]

The instance.cfg you have there is far too complicated and contains lots of irrelevant stuff.

I'd rather put up a demo.cfg which only configures an instance without all the other development related tools. I think 'demo' is more appropriate here, as you would never run Zope in production with a direct file storage.

[Charlie_X (charlie)]

You're right something more stripped down would be even better, which is why I added the config here rather than working on the repository. It leaves more space for expository comments - anyone who is new to Zope is going to be flummoxed by an uncommented buildout - the sample configuration from the buildout page is probably a good place to start.

I do think that we should retire the instructions for mkzopeinstance. There is no point in having a virtual environment and a target Zope instance. Buildout with a cache is much better for that. I'm working on the instructions for Windows having recently, ahem, mastered virtualenv on Windows.

[Charlie_X (charlie)]

My svn isn't working. Suggested replacement for INSTALL-buildout.rst

[Charlie_X (charlie)]

Suggested replacement for a demo install with instructions for Windows.

[Hanno Schlichting (hannosch)]

It looks like you are requiring buildout in the simple 'install.rst' instructions now. Tres refactored the install docs a while ago and *not* requiring buildout for the simple install was an explicit goal. Otherwise there's no point in having an extra install section for buildout.

I think your 'demo.cfg' based instructions should replace the install-buildout file, but the simple instructions should be left in place.

One more issue: You are pointing to bootstrap.py and demo.cfg URLs from Subversion. That's not acceptable for any installation instructions. URLs of source code internals are never guaranteed to be stable or available. If we want to point to those two files, we can add them to the KGS at http://download.zope.org/Zope2/index/2.13.6/. Always copying those files is a rather simple change in the z2.release scripts I can do.

[Charlie_X (charlie)]

I don't think the simple install is that simple - set up a virtualenv, install Zope and set up an instance in a separate folder: "Always use mkzopeinstance to create instances outside the virtualenv environment."

/path/to/virtualenv
/different/path/to/zopeinstance

Yuck!

But maybe it's just the order in the index. I think we should start with a really easy demo buildout and then offer a mkzopeinstance approach, although I really don't think it makes sense to offer this anymore. The install-buildout page could be replaced by a link to the developer instructions.

bin/pip install zc.buildout && wget path/to/demo.cfg && bin/buildout -c demo.cfg

Maybe this could be condensed to a bin/pip install Zope2instance? Which just bootstraps buildout and then runs the buildout?

You're right, of course, about the where the files should be. I was just spelling out the missing requirements in a testable way.

[M.-A. Lemburg (mal-egenix)]

Hanno Schlichting wrote:
> It looks like you are requiring buildout in the simple 'install.rst'
> instructions now. Tres refactored the install docs a while ago and *not*
> requiring buildout for the simple install was an explicit goal.
> Otherwise there's no point in having an extra install section for
> buildout.
>
> I think your 'demo.cfg' based instructions should replace the install-
> buildout file, but the simple instructions should be left in place.

From a user perspective, having just one generally accepted
installation method is a lot better than having multiple ones.

Since buildout today is the de-facto standard for Zope and
Plone installations, I think dropping the other options will
actually improve the user experience, even if buildout can
be confusing at first.

In order to help users get Zope up and running for the
first time, it is more important to settle on one method
which then is documented in all details.

The default Plone buildout.cfg file is a good example
of how this can be done.

If you want to improve the experience some more, it would
also be useful to provide a .tar.gz file that already includes
all required eggs in already downloaded (but not yet installed)
form.

Again, the Plone folks provide a good example of how this can
be done.

This has the advantage of not requiring network access for
a simple default install and also speeds up the installation
a lot.

Cheers,
--
Marc-Andre Lemburg
eGenix.com

Professional Python Services directly from the Source (#1, Apr 30 2011)
>>> Python/Zope Consulting and Support ... http://www.egenix.com/
>>> mxODBC.Zope.Database.Adapter ... http://zope.egenix.com/
>>> mxODBC, mxDateTime, mxTextTools ... http://python.egenix.com/
________________________________________________________________________
2011-06-20: EuroPython 2011, Florence, Italy 51 days to go

::: Try our new mxODBC.Connect Python Database Interface for free ! ::::

   eGenix.com Software, Skills and Services GmbH Pastor-Loeh-Str.48
    D-40764 Langenfeld, Germany. CEO Dipl.-Math. Marc-Andre Lemburg
           Registered at Amtsgericht Duesseldorf: HRB 46611
               http://www.egenix.com/company/contact/

[Colin Watson (cjwatson)]

The zope2 project on Launchpad has been archived at the request of the Zope developers (see https://answers.launchpad.net/launchpad/+question/683589 and https://answers.launchpad.net/launchpad/+question/685285). If this bug is still relevant, please refile it at https://github.com/zopefoundation/zope2.