add install notes for classic ui, pip and buildout method #1701
Conversation
|
@petschki @MrTango @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:
Please let me know. Thank you! |
|
See also #1353 |
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. |
|
@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? |
|
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? |
Buildout vs. pip
When it comes to product development you need to mix stable package releases with source checkouts. Advantages:
Disadvantages:
ZEOThe 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. |
docs/classic-ui/install.md
Outdated
| eggs = | ||
| Plone | ||
| ``` | ||
|
|
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
@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.
docs/classic-ui/install.md
Outdated
|
|
||
| Now you can call the url `http://localhost:8080` in your browser and you can add a **Classic UI Plone site** | ||
|
|
||
| Let's have fun with Plone! |
There was a problem hiding this comment.
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.
|
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. |
| Examples include the following. | ||
|
|
||
| - pip based install method | ||
| - buildout based install method |
There was a problem hiding this comment.
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
| Let's have fun with Plone! | ||
|
|
||
|
|
||
| ### Example to start the instance via systemd |
There was a problem hiding this comment.
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.
|
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. |
|
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: 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... |
|
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. |
|
@1letter @MrTango @stevepiercy I haven't forgotten about this...I'm looking at it again now and trying to figure out what we should do with it. I'm convinced we should have a doc about how to install Classic UI with buildout. There are enough existing projects and people using it, and the recent maintenance on buildout makes me less scared that it's a dead end. It can have a disclaimer that it might not be the best place to start for people who are new to Plone. I'm okay with removing the "Create a project with Classic UI" doc I wrote that uses cookieplone. I'm also okay with keeping it. I'm aware that the template for creating a Classic UI project still needs some work, and I'd like to discuss how to make it better. I'll ask some follow-up questions to @MrTango further below about that... I have mixed feelings about the part of these notes that covers pip-based installation. On the one hand, it is kind of useful to have these notes in brief form like this. On the other hand, it's not clear to me what audience we should direct to these notes. Wouldn't a newcomer to Plone prefer to run the cookieplone template and then use the make commands it includes (which do the same steps in a more automated way)? If we do keep this part, I agree with @stevepiercy that it belongs in a separate chapter, to make it clearer that it's a separate installation method from the others. The stuff about systemd is pretty specific. I guess that's useful if you are installing on a Linux system that uses systemd. But I'm more familiar with other tools like supervisor. Maybe this should be a separate how-to in the "Manage Plone" section, titled "Manage Plone processes with systemd on Linux" The stuff about ZEO is also pretty specific. These days lots of people use Relstorage instead of ZEO if they need a multi-process Plone installation. Now my questions for @MrTango...
Could you be more specific about what changes felt like too much? Some of it is intentional to try to follow current practices in the broader Python world, but I'd like to at least be aware of what felt confusing.
It is definitely the future way for Volto projects, and I would already use it if you're starting a new Volto project. We just can't call it officially the new way until Plone 6.1 + Volto 18 are finally released. Could you be more specific about what was broken when you tried it? I'd like to help make sure it works.
Which parts were not of interest for classic UI? Part of the point of Cookieplone is that we can have multiple templates and we can have optional sub-templates... so if necessary, it should be possible to set up a separate "Classic UI Project" template that is closer to what you are looking for, if you can help me understand what that is. |
+1, we should list the modern way first, but have the buildout accessible for people who are looking for it.
We can have both, let's say we have the single steps written down, which also helps people building on that information. Regarding the systemd i agree, we could put this together with supervisor PM2 and co, as a general documentation into deployment info's. It is not really specific to classic ui. ZEO and RelStorage are for me on the same level of importants, they are both widely used out there. But we could keep details to this also inside deployment best practices and link it from the installation chapters. To the other questions: In general i get the point of the new structure in cookieplone. I was talking with Erico about it in Ferrara. Project vs Add-on, is the question here. I get that in many projects you might just add your customization's inside a project-add-on. But then you also nest other add-on's inside this project-add-on. One might ask what is an add-on here really? So this is a change in how projects are structured and I'm not sure if it's worth the confusion. The alternative, we where using so far is a policy add-on next to what ever else people pull in and maybe customize. Also we should not forget people who just heard of Plone and want to install it on there machine to try it out. So what ever we document or provide in tooling, it has to be as lean as possible. Things like JavaScript calling Python tools like pre-commit which in some cases gives you trouble with dependencies, do not help. The same goes in the opposite direction, a Plone backend skeleton tool should not require me to setup a JavaScript environment, until a want to create a JavaScript stack like the Volto Frontend. Both happened with recent approaches. Maybe because the tooling tried a bit too much to automate both worlds. To rap this up, i like to have some simple docs for the two ways people setup backend / Classic UI. |
|
@MrTango Okay, you've convinced me (well, I've been realizing slowly over the past month) that we're not going to achieve a single one-size-fits-all recommendation for how to install Plone. I'm working today on a PR that will propose an "Admin Guide" section for how-tos related to installing, operating, configuring, and deploying Plone. This effort has several moving parts:
I won't tackle systemd and ZEO today, but I think they could fit in the Admin Guide as well. |
I've been skeptical about this in the past, but you're right, these projects do exist, especially for people who are new to Plone.
I'm confused about the change you see here. The alternative you mentioned (policy add-ons that are on an equal footing to installed add-ons) is the approach Cookieplone uses for both backend and frontend packages. At least that's how I have it in my head, did I overlook something obvious?
There's a tension because we want to make it possible to start as simple as possible, but we also want to make it as easy as possible to add in the missing pieces as you need them, without needing to start over on a different path. This is indeed hard to get right. |
|
@1letter @MrTango @stevepiercy Here's my new attempt at incorporating the above feedback and the buildout-based and pip-based install instructions from this PR: #1746. It still has some todo items, but sharing now so you can give feedback on the general direction. |
|
I'm closing this PR in favor of #1746. I'll address any remaining linked issues and comments in new issues and PRs. Thank you for starting the ball rolling! |
📚 Documentation preview 📚: https://plone6--1701.org.readthedocs.build/