Add installation documentation#1240
Conversation
This is an edited copy of what I included in the recent release notes. See: https://dist.plone.org/release/6.0.0a4/RELEASE-NOTES.md For the moment it includes a section on how to install Volto. This is a candidate for removal because the Volto docs are included automatically and I point to it. But the Volto docs also talk about how to install a backend. So maybe keep for now and improve later. I called the main file `installation.md`. I am fine with renaming this to `installing.md` or `install.md` if that sounds more natural to a native speaker. I will want to point to this file from the new release notes, so best pick a name now and stick with it.
✅ Deploy Preview for 6-dev-docs-plone-org ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
|
I'll complete my review later tonight. But for now... We have many ways to install Plone—or parts of Plone such as Volto, backend, and Classic UI—but all of them lack context. We need to add context. For example: DevelopmentBackend onlyIf you want to install, develop, test, or write documentation for Plone backend only, then use the following instructions. Volto onlyIf you want to install, develop, test, or write documentation for Volto only, then use the following instructions. ProductionIf you want to deploy Plone 6 to a production environment, then use the following instructions. I lack a full understanding of how all the Plone pieces fit together, but I think the above examples describe what I seek. In other words, the Plone Installation docs should be an entry point for all users which then point them in the right direction. |
|
I looked at this more closely. I realized that we need a better place for installation documentation, and any other item that does not fit into any of the current primary navigation items. We currently have: I firmly believe that "Install" belongs in the primary navigation. Would you please create a new directory |
|
Also this is more than just backend installation. You're talking about Plone 6 "the whole thing" Installation. That's why I think it belongs at a top navigation level. |
That makes sense.
Done. |
stevepiercy
changed the title
stevepiercy
changed the title
…al contribution. This version provides context, structure, and order, leading the developer down the path to a successful installation experience according to their specific needs. This is still a work in progress. Additional review is needed.
|
@mauritsvanrees thank you! I decided I would take a stab as well, and pushed a commit with an overhaul, based on your initial contribution. This version is a work in progress. It needs review from several core contributors. Who else should review this? @sneridagh @tiberiuichim @jensens @ericof others? I approached this with the view of "I am new to Plone 6. How do I install it?" I think that includes pretty much anyone who is not a core Plone package developer at this point. 😉 That audience probably does not know the differences between a Docker and manual installation, or choosing Classic UI or Volto for a fronted. Finally I firmly believe that we must have one, and only one, place for Plone installation documentation. As such I opened a new issue with Volto. I hope to resolve discrepancies and maintenance issues there. Each package should have its own documentation for development purposes, such as for running tests, and that should be separate from installation. |
| # Install Plone 6 with constrained requirements with pip | ||
| bin/pip install Plone -c https://dist.plone.org/release/6.0.0a4/constraints.txt | ||
| # Create a Plone 6 site with the given username and password in the current directory | ||
| bin/mkwsgiinstance -u admin:admin -d . |
There was a problem hiding this comment.
mkwsgiinstance is not enough, like no blobs configured. I would like to point to cookiecutter-zope-instance here.
There was a problem hiding this comment.
this one https://github.com/bluedynamics/cookiecutter-zope-instance/
I can move it to zopefoundation or plone repos if this feels better.
There was a problem hiding this comment.
Yeah, and the ensuing warning is... not a good look. I will trust you and other core developers to update this as you feel is best.
There was a problem hiding this comment.
Well, we have two sprints now, and I am at both. This is part of our installation story, so stay tuned. As said, mkwsgiinstance wont make anybody happy.
There was a problem hiding this comment.
FYI, I will also remotely participate in both upcoming sprints. I would be happy to act as a rubber duck.
|
@stevepiercy Your update LGTM. |
ericof
left a comment
ericof
left a comment
There was a problem hiding this comment.
LGTM, let's merge it and built on top of it
6 participants
As promised during the previous Plone 6 meeting, and done within the last hour before the next meeting. :-)
I am not sure if I will be able to make it to this meeting, still need to get a car, a daughter, and possibly a son before that. :-D
This is an edited copy of what I included in the recent release notes. See:
https://dist.plone.org/release/6.0.0a4/RELEASE-NOTES.md
For the moment it includes a section on how to install Volto. This is a candidate for removal because the Volto docs are included automatically and I point to it. But the Volto docs also talk about how to install a backend. So maybe keep for now and improve later.
I called the main file
installation.md. I am fine with renaming this toinstalling.mdorinstall.mdif that sounds more natural to a native speaker. I will want to point to this file from the new release notes, so best pick a name now and stick with it.Note: this is my first PR here with MyST, so I am still a rookie on that count. Patience and guidance are welcome. :-)