add install notes for classic ui, pip and buildout method

[1letter]

• Closes Update: buildout docs #278
• Closes Add virtualenv + zc.buildout based installation to install docs #499

---

📚 Documentation preview 📚: https://plone6--1701.org.readthedocs.build/

[1letter]

@petschki @MrTango @stevepiercy
here my first proposal for quick installation instructions via pip or buildout

[stevepiercy]

@1letter thanks for the quick contribution!

I quickly scanned the PR, and I am left with the question of what can the developer do next with the installation? I assume options include:

• just play around with the installation
• create a project
• Contribute to Plone (maybe not this, because we recently published extensive documentation for that)

Please let me know. Thank you!

[stevepiercy]

See also #1353

[1letter]

• just play around with the installation
• create a project

This two points are valid. The instructions are only for "how can i quick install Plone", not more intensions by me. Perhaps @MrTango has an idea. The purpose to document this steps come from him.

[1letter]

@stevepiercy can you review the wording and the spelling of the new content in this chapter, please?

@MrTango i use my own simple "installer" script for a zeo installation. should this go to the official docs, i'm not sure?

[stevepiercy]

Before I can review this PR, I still need more context. Documentation must be approachable for newcomers.

Why would I choose one installation method over another? I don't want to publish a method without a reason to use it.

System requirements must align with what is officially supported for Plone 6.x. 6.0 supports Python 3.8 - 3.12. 6.1 supports 3.10 - 3.12. https://plone.org/download/release-schedule.

Are there advantages or disadvantages to one method over the other?

What is this ZEO server stuff? Do I need it? If so, then why?

Why should I choose a ZEO server via client installation versus a cluster via systemd?

[petschki]

Buildout vs. pip

zc.buildout is a python based installation approach which helps you with "recipes" to automate development and productive installations. But it is kind of a "plone community only" approach, so reading https://github.com/plone/buildout.coredev/blob/6.1/README-make.md#using-the-makefile-in-buildoutcoredev there it says:

Buildout is not well known outside of the Plone world, and it can have problems when a new pip or setuptools version is released. So we are busy putting pip on the same level as Buildout for doing core development. See plone/Products.CMFPlone#3670.

When it comes to product development you need to mix stable package releases with source checkouts.buildout helps you with an extension called mr.developer while in pip installations you have to use mxdev to create the "requirements" and "constraints" for your python environment.

Advantages:

zc.buildout

• mature and feature rich for plone development and productive environments.
• Has several "recipes" to automate various installation tasks.

pip

• known by a broad community.
• Maintained and improved by the python community.

Disadvantages:

• zc.buildout is only known and maintained by the plone community
• pip needs more effort/knowledge to automate installations (like you're used to in buildout? -> I'm not using pip based installations on productive environements)

ZEO

The ZEO server is used to run the ZODB in a separate process where multiple Zope/WSGI clients can connect to. This is used to scale productive installations for high traffic sites to distribute the requests with a loadbalancer to more than one worker.

[MrTango]

i would add the following command, which creates the bin/buildout script, so venv does need to be used after that anymore.

buildout bootstrap

then deactivate venv and jut run ./bin/buildout when ever something in the buildout config has changed.

[mauritsvanrees]

@MrTango Are you actually using the buildout bootstrap command regularly? I was just wondering if I would remove this (and the buildout init command) in a new major version of zc.buildout.

[MrTango]

maybe also a zeo setup?

[stevepiercy]

After #1714 is merged, then this documentation should be moved into /install and its index.md updated.

There's also a note that buildout is not documented in Plone 6, which will need to be removed.

Finally, I want to be absolutely clear with newcomer Plone developers that if they want to develop a project with Classic UI, then they must choose one method, either Cookieplone or buildout, and we should also declare one to be "preferred" and the other "deprecated" or "alternative". I'm heavily leaning toward Cookieplone as "preferred".

In any case, experienced developers will do whatever works for them, and this PR will serve as a resource for many of them.

[stevepiercy]

• Add a note not to run as root. See https://community.plone.org/t/copying-a-plone-site-how-to-give-permissions-to-old-data-fs/1846 as reported in Improve docs about root vs $user for running buildout #563

[stevepiercy]

Finally, I want to be absolutely clear with newcomer Plone developers that if they want to develop a project with Classic UI, then they must choose one method, either Cookieplone or buildout, and we should also declare one to be "preferred" and the other "deprecated" or "alternative". I'm heavily leaning toward Cookieplone as "preferred".

Per #1714 (comment) we need both install methods documented.

We also now have some new structure in the docs where this PR can be moved. I'll update the PR accordingly.

[stevepiercy]

This is a good first pass, but I'm stuck until I get more direction from y'all.

[stevepiercy]

I would remove the above section and break apart this file into two new pages:

• Install Classic UI via pip
• Install Classic UI via buildout

[stevepiercy]

I am not sure why the following three examples are in "Install". Aren't these configuration items for how to manage an instance, not install one?

If so, we have a new home for such stuff in Manage Plone. The content currently only has Cookieplone based stuff, and we can add buildout and pip based stuff as needed. Please let me know.

[MrTango]

we should replace the existing Create a project classic ui, with this, not have both.

[stevepiercy]

we should replace the existing Create a project classic ui, with this, not have both.

I'd like @davisagli's opinion. I don't want to get in the way of what works and can be reproduced from what is published. I understand the published way is not ready for developers, and we should mitigate that with a disclaimer, such as "This method has no published test examples available for developers, and some methods may not work as desired. Until then, to install Plone for development of the backend and Classic UI, use the method in #1701."

But neither is this ready to publish in its current state. It's stalled. I'm awaiting responses to my review from participants involved with this issue. We can chat in Discord to work out the details, if that helps. I want to get this published, and not hang around incomplete for months, especially with PloneConf fast approaching.

[davisagli]

Sorry, I was on vacation for the past week.

Do people who work on Classic UI sites still prefer to use buildout? If so, then I can certainly understand the suggestion that that is what should be documented.

It kind of makes a challenge for how to organize the documentation though, since the commands for running the instance and doing development tasks are different. So then in any case where we have a doc that needs to mention starting the instance or installing an add-on or whatever task, we have to do one of the following:
a. Have two different chapters, one for buildout-based projects and one for cookieplone-based projects.
b. Have a single chapter that shows different ways to run the command depending on what kind of project you have.

This is why I tried to add the "Create a project with Classic UI" chapter based on cookieplone, so that there can be some consistency. But my attempt may have been misguided.

The problem really goes beyond the buildout-vs-cookieplone question. We have similar problems in dealing with the differences between the old cookiecutter-plone-starter template and cookieplone, or the differences between developing and using Classic UI vs developing and using Volto, or the differences between unittest and pytest...

It brings up some fundamental questions about whether we're documenting one product or two, and where we draw the lines. The reality is that we have different groups of people in the community who prefer different tools. Not having documentation for the tools you want to use sucks. Trying to support all possible tools for people who are new to the community also sucks. I'm a little stuck on figuring out how to resolve it all...

[MrTango]

thx @davisagli for your comments.

My problem with some of the new templates, that they are doing to much and also changing the way packages are organized. If you come from an existing classic ui project and somebody gives you cookieplone, you are lost.

What we tried to document here is, a minimal setup for both the still often used and well know buildout way and the new way to do it with out buildout.

If cookieplone is the future way of setting things up for Volto setups, thats fine, but right now it is not yet finalized and still heart some lose ends in that setup. And last time i tried (a month ago or so) the backend part was completely broken.

For the classic ui stack, i would not bring it in, because it changes to much and half of it is not of interest for classic ui setups. Let's solve this for Volto and keep classic setups minimal.