From dda3bd49661eae122a581d4a40ca7dbd86406ccf Mon Sep 17 00:00:00 2001 From: David Glick Date: Fri, 25 Oct 2024 14:55:29 -0700 Subject: [PATCH 01/29] Start Admin Guide --- .../containers/examples/haproxy-plone-zeo.md | 0 .../containers/examples/index.md | 0 .../containers/examples/nginx-plone.md | 0 .../examples/nginx-volto-plone-postgresql.md | 0 .../examples/nginx-volto-plone-zeo.md | 0 .../containers/examples/nginx-volto-plone.md | 0 .../examples/traefik-volto-plone-varnish.md | 0 .../containers/images/backend.md | 0 .../containers/images/frontend.md | 0 .../containers/images/index.md | 0 .../containers/images/zeo.md | 0 .../containers/index.md | 2 +- docs/admin-guide/index.md | 43 ++++ docs/admin-guide/install-buildout.md | 105 ++++++++ .../install-cookieplone.md} | 19 +- docs/admin-guide/install-pip.md | 88 +++++++ .../install-plonestarter.md} | 18 +- .../index.md => admin-guide/upgrade.md} | 4 +- docs/classic-ui/theming/barceloneta.md | 2 - .../make-build-backend-walk-through.md | 2 +- docs/conceptual-guides/package-management.md | 2 +- docs/conf.py | 6 +- docs/contributing/index.md | 2 +- docs/glossary.md | 4 + docs/index.md | 2 +- docs/install/create-project-classic-ui.md | 229 ------------------ docs/install/index.md | 81 ++++--- docs/manage/backend.md | 2 +- 28 files changed, 322 insertions(+), 289 deletions(-) rename docs/{install => admin-guide}/containers/examples/haproxy-plone-zeo.md (100%) rename docs/{install => admin-guide}/containers/examples/index.md (100%) rename docs/{install => admin-guide}/containers/examples/nginx-plone.md (100%) rename docs/{install => admin-guide}/containers/examples/nginx-volto-plone-postgresql.md (100%) rename docs/{install => admin-guide}/containers/examples/nginx-volto-plone-zeo.md (100%) rename docs/{install => admin-guide}/containers/examples/nginx-volto-plone.md (100%) rename docs/{install => admin-guide}/containers/examples/traefik-volto-plone-varnish.md (100%) rename docs/{install => admin-guide}/containers/images/backend.md (100%) rename docs/{install => admin-guide}/containers/images/frontend.md (100%) rename docs/{install => admin-guide}/containers/images/index.md (100%) rename docs/{install => admin-guide}/containers/images/zeo.md (100%) rename docs/{install => admin-guide}/containers/index.md (97%) create mode 100644 docs/admin-guide/index.md create mode 100644 docs/admin-guide/install-buildout.md rename docs/{install/create-project-cookieplone.md => admin-guide/install-cookieplone.md} (94%) create mode 100644 docs/admin-guide/install-pip.md rename docs/{install/create-project.md => admin-guide/install-plonestarter.md} (93%) rename docs/{upgrade/index.md => admin-guide/upgrade.md} (90%) delete mode 100644 docs/install/create-project-classic-ui.md diff --git a/docs/install/containers/examples/haproxy-plone-zeo.md b/docs/admin-guide/containers/examples/haproxy-plone-zeo.md similarity index 100% rename from docs/install/containers/examples/haproxy-plone-zeo.md rename to docs/admin-guide/containers/examples/haproxy-plone-zeo.md diff --git a/docs/install/containers/examples/index.md b/docs/admin-guide/containers/examples/index.md similarity index 100% rename from docs/install/containers/examples/index.md rename to docs/admin-guide/containers/examples/index.md diff --git a/docs/install/containers/examples/nginx-plone.md b/docs/admin-guide/containers/examples/nginx-plone.md similarity index 100% rename from docs/install/containers/examples/nginx-plone.md rename to docs/admin-guide/containers/examples/nginx-plone.md diff --git a/docs/install/containers/examples/nginx-volto-plone-postgresql.md b/docs/admin-guide/containers/examples/nginx-volto-plone-postgresql.md similarity index 100% rename from docs/install/containers/examples/nginx-volto-plone-postgresql.md rename to docs/admin-guide/containers/examples/nginx-volto-plone-postgresql.md diff --git a/docs/install/containers/examples/nginx-volto-plone-zeo.md b/docs/admin-guide/containers/examples/nginx-volto-plone-zeo.md similarity index 100% rename from docs/install/containers/examples/nginx-volto-plone-zeo.md rename to docs/admin-guide/containers/examples/nginx-volto-plone-zeo.md diff --git a/docs/install/containers/examples/nginx-volto-plone.md b/docs/admin-guide/containers/examples/nginx-volto-plone.md similarity index 100% rename from docs/install/containers/examples/nginx-volto-plone.md rename to docs/admin-guide/containers/examples/nginx-volto-plone.md diff --git a/docs/install/containers/examples/traefik-volto-plone-varnish.md b/docs/admin-guide/containers/examples/traefik-volto-plone-varnish.md similarity index 100% rename from docs/install/containers/examples/traefik-volto-plone-varnish.md rename to docs/admin-guide/containers/examples/traefik-volto-plone-varnish.md diff --git a/docs/install/containers/images/backend.md b/docs/admin-guide/containers/images/backend.md similarity index 100% rename from docs/install/containers/images/backend.md rename to docs/admin-guide/containers/images/backend.md diff --git a/docs/install/containers/images/frontend.md b/docs/admin-guide/containers/images/frontend.md similarity index 100% rename from docs/install/containers/images/frontend.md rename to docs/admin-guide/containers/images/frontend.md diff --git a/docs/install/containers/images/index.md b/docs/admin-guide/containers/images/index.md similarity index 100% rename from docs/install/containers/images/index.md rename to docs/admin-guide/containers/images/index.md diff --git a/docs/install/containers/images/zeo.md b/docs/admin-guide/containers/images/zeo.md similarity index 100% rename from docs/install/containers/images/zeo.md rename to docs/admin-guide/containers/images/zeo.md diff --git a/docs/install/containers/index.md b/docs/admin-guide/containers/index.md similarity index 97% rename from docs/install/containers/index.md rename to docs/admin-guide/containers/index.md index 5aef61ee6..d5475b532 100644 --- a/docs/install/containers/index.md +++ b/docs/admin-guide/containers/index.md @@ -14,7 +14,7 @@ myst: The Plone 6 images have all the system requirements, prerequisites, and Plone 6 already installed, except those requirements needed for running the container engine itself. Using containers is the easiest way to deploy Plone 6. -Containers may also be used when {doc}`creating a Plone project <../create-project>` and {doc}`contributing to Plone `. +Containers may also be used when {doc}`creating a Plone project `. The Plone 6 container images are compliant with the [Open Container Initiative (OCI)](https://opencontainers.org/). They should work with any OCI-compliant container engine for developing, managing, and running Plone 6 images. diff --git a/docs/admin-guide/index.md b/docs/admin-guide/index.md new file mode 100644 index 000000000..0d701262e --- /dev/null +++ b/docs/admin-guide/index.md @@ -0,0 +1,43 @@ +--- +myst: + html_meta: + "description": "How to install, operate, configure, and deploy Plone 6" + "property=og:description": "How to install, operate, configure, and deploy Plone 6" + "property=og:title": "Admin Guide" + "keywords": "Plone 6, admin, install, configuration, deploy" +--- + +(admin-index-label)= + +# Admin Guide + +In this part of the documentation, you can find how to install, operate, configure, and deploy Plone. + + +```{toctree} +:caption: Install +:maxdepth: 1 + +install-cookieplone +install-buildout +install-pip +install-plonestarter +``` + +```{toctree} +:caption: Operate +:maxdepth: 1 + +upgrade +``` + +```{toctree} +:maxdepth: 1 +:caption: Deploy + +containers/index +``` + + +To do: +- move and update Manage section diff --git a/docs/admin-guide/install-buildout.md b/docs/admin-guide/install-buildout.md new file mode 100644 index 000000000..dbf8a2b3b --- /dev/null +++ b/docs/admin-guide/install-buildout.md @@ -0,0 +1,105 @@ +--- +myst: + html_meta: + "description": "Install Plone with Buildout" + "property=og:description": "Install Plone with Buildout" + "property=og:title": "Install Plone with Buildout" + "keywords": "Plone 6, install, Classic UI, buildout" +--- + +(install-buildout-label)= + +# Install Plone with Buildout + +This chapter describes how you can install Plone using {term}`Buildout`. + +This is one way to install Plone with the Classic UI. +Using Buildout will be the most familiar approach for admins who have experience with Plone 3, 4, or 5. + +```{seealso} +For other installation options, see {ref}`get-started-install-label`. +``` + +(install-buildout-prerequisites)= + +## Prerequisites + +- Python 3.10 or greater + +On Debian-based Linux systems you can install Python with the following command: + +```shell +sudo apt install python3.12 python3.12-dev python3.12-venv +``` + +## Installation + +Select a directory of your choice: + +```shell +mkdir -p /opt/plone && cd /opt/plone +``` + +Create a Python virtual environment: + +```shell +python3 -m venv . +``` + +Install the minimal Python packages needed in order to run Buildout: + +```shell +bin/pip install -r https://dist.plone.org/release/6-latest/requirements.txt +``` + +Create a `buildout.cfg` file in your directory with the following contents: + +```cfg +[buildout] +extends = + https://dist.plone.org/release/6-latest/versions.cfg + +parts = + instance + +[instance] +recipe = plone.recipe.zope2instance +user = admin:admin +http-address = 8080 +eggs = + Plone +``` + +Run buildout: + +```shell +bin/buildout +``` + +## Run Plone in foreground mode + +Start the instance for a quick test in foreground mode: + +```shell +bin/instance fg +``` + +Your instance starts in foreground mode, which is only advisable for troubleshooting or for local demonstration purposes. + +Now you can call the url `http://localhost:8080` in your browser and you can add a **Classic UI Plone site**. + +## Start Plone as a background service + +Start the instance: + +```shell +bin/instance start +``` + +## Stop Plone as a background service + +Stop the instance: + +```shell +bin/instance stop +``` diff --git a/docs/install/create-project-cookieplone.md b/docs/admin-guide/install-cookieplone.md similarity index 94% rename from docs/install/create-project-cookieplone.md rename to docs/admin-guide/install-cookieplone.md index 5f2122aff..651a1941d 100644 --- a/docs/install/create-project-cookieplone.md +++ b/docs/admin-guide/install-cookieplone.md @@ -1,25 +1,28 @@ --- myst: html_meta: - "description": "Create a Plone project with the Volto frontend (development or pre-release)" - "property=og:description": "Create a Plone project with the Volto frontend (development or pre-release)" - "property=og:title": "Create a Plone project with the Volto frontend (development or pre-release)" + "description": "Install Plone with Cookieplone" + "property=og:description": "Install Plone with Cookieplone" + "property=og:title": "Install Plone with Cookieplone" "keywords": "Plone, Plone 6, Volto, create, project, install, Cookieplone" --- -(create-project-cookieplone-label)= +(install-cookieplone-label)= -# Create a project with Volto (development or pre-release) +# Install Plone with Cookieplone -This chapter describes how you can create a web application using the latest **development release** version of Plone with **Volto 18 or later** for the frontend, while having full control over its development and deployment. +This chapter describes how you can create a web application using the {term}`Cookieplone` template. + +This template is the recommended way to start a new Plone project using the Volto frontend. +It also includes tools for development and deployment. ```{seealso} -For other installation options, see {doc}`/install/index`. +For other installation options, see {ref}`get-started-install-label`. ``` ```{versionadded} Volto 18.0.0-alpha.43 -{term}`Cookieplone` is now the method to create a Plone project with unstable versions of Volto, version 18.0.0-alpha.43 and above. +{term}`Cookieplone` was added as the recommended template to create a Plone project with Volto starting in Volto 18.0.0-alpha.43 and above. ``` diff --git a/docs/admin-guide/install-pip.md b/docs/admin-guide/install-pip.md new file mode 100644 index 000000000..5dcb2ae4a --- /dev/null +++ b/docs/admin-guide/install-pip.md @@ -0,0 +1,88 @@ +--- +myst: + html_meta: + "description": "Install Plone with pip" + "property=og:description": "Install Plone with pip" + "property=og:title": "Install Plone with pip" + "keywords": "Plone 6, install, Classic UI, pip" +--- + +(install-pip-label)= + +# Install Plone with pip + +This chapter describes how you can install Plone using {term}`pip`. + +This is one way to install Plone with the Classic UI. +It provides a basic installation without many additional tools to help with development. + +```{seealso} +For other installation options, see {ref}`get-started-install-label`. +``` + +## Prerequisites + +- Python 3.10 or greater + +On Debian-based systems you can install Python with following command: + +```shell +sudo apt install python3.12 python3.12-dev python3.12-venv +``` + +## Installation + +Select a directory of your choice: + +```shell +mkdir -p /opt/plone +cd /opt/plone +``` + +Create a Python virtual environment: + +```shell +python3 -m venv . +``` + +Install Plone and a helper package: + +```shell +bin/pip install -c https://dist.plone.org/release/6.0-latest/constraints.txt Plone pipx +``` + +## Create a Zope instance + +Create a file `instance.yaml` with the following contents: + +```yaml +# please change the password to a secure token! +default_context: + initial_user_name: "admin" + initial_user_password: "admin" + wsgi_listen: "localhost:8080" + debug_mode: false + verbose_security: false + db_storage: "direct" + environment: { + "zope_i18n_compile_mo_files": true, + } +``` + +Now run the {term}`cookiecutter` tool to create configuration for a Zope instance: + +``` +bin/pipx run cookiecutter -f --no-input --config-file instance.yaml gh:plone/cookiecutter-zope-instance +``` + +## Start Plone in foreground mode + +Start the instance for a quick test: + +```shell +bin/runwsgi -v instance/etc/zope.ini +``` + +Your instance starts in foreground mode, which is only advisable for troubleshooting or for local demonstration purposes. + +Now you can call the url `http://localhost:8080` in your browser and you can add a **Classic UI Plone site**. diff --git a/docs/install/create-project.md b/docs/admin-guide/install-plonestarter.md similarity index 93% rename from docs/install/create-project.md rename to docs/admin-guide/install-plonestarter.md index 7e7ab358f..7e8a25317 100644 --- a/docs/install/create-project.md +++ b/docs/admin-guide/install-plonestarter.md @@ -1,23 +1,27 @@ --- myst: html_meta: - "description": "Create a Plone project with the Volto frontend (stable release)" - "property=og:description": "Create a Plone project with the Volto frontend (stable release)" - "property=og:title": "Create a Plone project with the Volto frontend (stable release)" + "description": "Install Plone with cookiecutter-plone-starter (deprecated)" + "property=og:description": "Install Plone with cookiecutter-plone-starter (deprecated)" + "property=og:title": "Install Plone with cookiecutter-plone-starter (deprecated)" "keywords": "Plone, Plone 6, Volto, create, project, install, cookiecutter" --- (create-a-project-label)= -# Create a project with Volto (stable release) +# Install Plone with cookiecutter-plone-starter (deprecated) -This chapter describes how you can create a web application using the current **stable release** version of Plone with **Volto 17 or earlier** for the frontend, while having full control over its development and deployment. +This chapter describes how you can create a web application using the {term}`cookiecutter-plone-starter` template. -```{seealso} -For other installation options, see {doc}`/install/index`. +```{deprecated} +This way of installing Plone is now deprecated. +It was the recommended way to start a new Plone project with **Plone 6.0** and **Volto 17 or earlier**. +For other installation options, see {ref}`get-started-install-label`. ``` +This template creates a web application using Plone with the Volto frontend, along with tools for development and deployment. + (install-packages-system-requirements-label)= diff --git a/docs/upgrade/index.md b/docs/admin-guide/upgrade.md similarity index 90% rename from docs/upgrade/index.md rename to docs/admin-guide/upgrade.md index b211116b6..be78a1e7f 100644 --- a/docs/upgrade/index.md +++ b/docs/admin-guide/upgrade.md @@ -3,13 +3,13 @@ myst: html_meta: "description": "Plone 6 upgrade Guide" "property=og:description": "Plone 6 upgrade guide" - "property=og:title": "Plone 6 upgrade guide" + "property=og:title": "Upgrade Plone" "keywords": "Plone, upgrade" --- (upgrade-guide-label)= -# Upgrade guide +# Upgrade Plone Plone has several components, each of which have their own upgrade guides: diff --git a/docs/classic-ui/theming/barceloneta.md b/docs/classic-ui/theming/barceloneta.md index 0080106f1..18c767c81 100644 --- a/docs/classic-ui/theming/barceloneta.md +++ b/docs/classic-ui/theming/barceloneta.md @@ -25,8 +25,6 @@ To create an add-on package with a Plone Classic UI theme, you need to install t - [Python (>=3.8)](https://www.python.org/) - [plonecli](https://pypi.org/project/plonecli/) -Read more about how to install prerequisites in {doc}`/install/create-project`. - (classic-ui-theming-barceloneta-create-a-classic-ui-theme-add-on-package-label)= diff --git a/docs/conceptual-guides/make-build-backend-walk-through.md b/docs/conceptual-guides/make-build-backend-walk-through.md index a39bc9cba..3c0ce4347 100644 --- a/docs/conceptual-guides/make-build-backend-walk-through.md +++ b/docs/conceptual-guides/make-build-backend-walk-through.md @@ -11,7 +11,7 @@ myst: # `make build-backend` details -This chapter assumes you have previously followed {doc}`/install/create-project`. +This chapter assumes you have previously followed {doc}`/admin-guide/install-plonestarter`. The `Makefile` at the root of your project invokes commands in `backend/Makefile`. Here are excerpts from `backend/Makefile` to show details of the `make build-backend` command. diff --git a/docs/conceptual-guides/package-management.md b/docs/conceptual-guides/package-management.md index 7e5dd4084..7e19bf175 100644 --- a/docs/conceptual-guides/package-management.md +++ b/docs/conceptual-guides/package-management.md @@ -61,4 +61,4 @@ You or your development tools, such as GNU Make, must perform that step. ```{todo} Why do we use pnpm? -``` \ No newline at end of file +``` diff --git a/docs/conf.py b/docs/conf.py index 43fd357ff..ca61b9e21 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -245,8 +245,12 @@ "contributing/plone-api": "/plone.api/contribute/index.html", "contributing/plone-restapi": "/plone.restapi/docs/source/contributing/index.html", "contributing/volto": "/volto/contributing/index.html", - "install/install-from-packages": "/install/create-project.html", + "install/containers/index": "/admin-guide/containers/index.html", + "install/create-project-cookieplone": "/admin-guide/install-cookieplone.html", + "install/create-project": "/admin-guide/install-plonestarter.html", + "install/install-from-packages": "/admin-guide/install-cookieplone.html", "manage/frontend": "/volto/addons/index.html", + "upgrade/index": "/admin-guide/upgrade.html", } diff --git a/docs/contributing/index.md b/docs/contributing/index.md index a5c78b3f0..84ad3a044 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -13,7 +13,7 @@ myst: This part of the documentation describes how to contribute to Plone, including all its projects and repositories under the Plone GitHub organization. -If instead you want to create a web application project using Plone, see {doc}`/install/create-project`. +If instead you want to create a web application project using Plone, see {ref}`get-started-install-label`. To contribute to any project in Plone, you must follow the policies of the [Plone Foundation](https://plone.org/foundation), [Plone GitHub organization](https://github.com/plone/) and the specific project. diff --git a/docs/glossary.md b/docs/glossary.md index d637dca9b..c1fe40db8 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -21,6 +21,10 @@ AWS Barceloneta The default theme for Plone 5. +Buildout + [Buildout](https://github.com/buildout/buildout/) is a Python-based tool for building and assembling applications from multiple parts, based on a configuration file. + It was the most common way of installing Plone 3, 4, and 5, and can still be used with Plone 6. + CMS Content Management System diff --git a/docs/index.md b/docs/index.md index 0ab3dbaca..2a7b9cba6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -32,8 +32,8 @@ Read the [documentation for the previous version, Plone 5](https://5.docs.plone. overview/index install/index +admin-guide/index manage/index -upgrade/index deployment/index volto/index plone.restapi/docs/source/index diff --git a/docs/install/create-project-classic-ui.md b/docs/install/create-project-classic-ui.md deleted file mode 100644 index 1826a1056..000000000 --- a/docs/install/create-project-classic-ui.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -myst: - html_meta: - "description": "Create a Plone project with Classic UI (stable release)" - "property=og:description": "Create a Plone project with Classic UI (stable release)" - "property=og:title": "Create a Plone project with Classic UI (stable release)" - "keywords": "Plone, Plone 6, Classic UI, create, project, install, cookiecutter, Cookieplone" ---- - - -(create-a-project-classic-ui-label)= - -# Create a project with Classic UI (stable release) - -This chapter describes how you can create a web application using the current **stable release** version of Plone with **Classic UI** for the frontend, while having full control over its development and deployment. - -```{seealso} -For other installation options, see {doc}`/install/index`. -``` - - -## System requirements - -Plone 6 has both hardware requirements and software prerequisites. - - -### Hardware requirements - -```{include} /_inc/_hardware-requirements.md -``` - -### Prerequisites for installation - -```{include} ../volto/contributing/install-operating-system.md -``` - -- Python {SUPPORTED_PYTHON_VERSIONS} -- {term}`pipx` -- {term}`GNU make` -- {term}`Git` - - -#### Python - -```{include} /_inc/_install-python.md -``` - - -#### pipx - -Install {term}`pipx`. - -```shell -pip install pipx -``` - - -#### Make - -```{include} ../volto/contributing/install-make.md -``` - - -#### Git - -```{include} ../volto/contributing/install-git.md -``` - - -## Generate the project - -After satisfying the prerequisites, generate the project. - -```shell -pipx run cookieplone backend_addon -``` - -You will be presented with a series of prompts. -You can accept the default values in square brackets (`[default-option]`) by hitting the {kbd}`Enter` key, or enter your preferred values. -For ease of documentation, we will use the default values. - -```{tip} -See the cookiecutter's README for how to [Use options to avoid prompts](https://github.com/collective/cookiecutter-plone-starter/?tab=readme-ov-file#use-options-to-avoid-prompts). -``` - -```{important} -For {guilabel}`Project Slug`, you must not use any of the Plone core package names listed in [`constraints.txt`](https://dist.plone.org/release/6.0-latest/constraints.txt). -Note that pip normalizes these names, so `plone.volto` and `plone-volto` are the same package. -``` - -```console -% pipx run cookieplone backend_addon -╭─────────────────────────────────── cookieplone ────────────────────────────────────╮ -│ │ -│ .xxxxxxxxxxxxxx. │ -│ ;xxxxxxxxxxxxxxxxxxxxxx; │ -│ ;xxxxxxxxxxxxxxxxxxxxxxxxxxxx; │ -│ xxxxxxxxxx xxxxxxxxxx │ -│ xxxxxxxx. .xxxxxxxx │ -│ xxxxxxx xxxxxxx: xxxxxxx │ -│ :xxxxxx xxxxxxxxxx xxxxxx: │ -│ :xxxxx+ xxxxxxxxxxx +xxxxx: │ -│ .xxxxx. :xxxxxxxxxx .xxxxx. │ -│ xxxxx+ ;xxxxxxxx +xxxxx │ -│ xxxxx +xx. xxxxx. │ -│ xxxxx: .xxxxxxxx :xxxxx │ -│ xxxxx .xxxxxxxxxx xxxxx │ -│ xxxxx xxxxxxxxxxx xxxxx │ -│ xxxxx .xxxxxxxxxx xxxxx │ -│ xxxxx: .xxxxxxxx :xxxxx │ -│ .xxxxx ;xx. ... xxxxx. │ -│ xxxxx+ :xxxxxxxx +xxxxx │ -│ .xxxxx. :xxxxxxxxxx .xxxxx. │ -│ :xxxxx+ xxxxxxxxxxx ;xxxxx: │ -│ :xxxxxx xxxxxxxxxx xxxxxx: │ -│ xxxxxxx xxxxxxx; xxxxxxx │ -│ xxxxxxxx. .xxxxxxxx │ -│ xxxxxxxxxx xxxxxxxxxx │ -│ ;xxxxxxxxxxxxxxxxxxxxxxxxxxxx+ │ -│ ;xxxxxxxxxxxxxxxxxxxxxx; │ -│ .xxxxxxxxxxxxxx. │ -│ │ -╰────────────────────────────────────────────────────────────────────────────────────╯ -╭─────────────────────────────────── Plone Addon ────────────────────────────────────╮ -│ Creating a new Plone Addon │ -╰────────────────────────────────────────────────────────────────────────────────────╯ - [1/7] Addon Title (Addon): - [2/7] A short description of your addon (A new addon for Plone): - [3/7] Author (Plone Community): - [4/7] Author E-mail (collective@plone.org): - [5/7] GitHub Username or Organization (collective): - [6/7] Python package name (collective.addon): - [7/7] Support headless Plone? - 1 - Yes - 2 - No - Choose from [1/2] (1): - -> Initialize Git repository -╭───────────────────────────── New addon was generated ──────────────────────────────╮ -│ │ -│ Addon │ -│ │ -│ Now, enter the repository run the code formatter with: │ -│ │ -│ make format │ -│ │ -│ start coding, and push to your organization. │ -│ │ -│ Sorry for the convenience, │ -│ The Plone Community. │ -│ │ -│ https://plone.org/ │ -╰────────────────────────────────────────────────────────────────────────────────────╯ -``` - - -## Install the project - -Change to your project directory. - -```shell -cd collective.addon -``` - -To install the project's dependencies, use the following command. - -```shell -make install -``` - -This will take a few minutes. -☕️ - -When the process completes successfully, it will exit with no message. - -```{include} /_inc/_install-pillow.md -``` - - -## Start Plone - -To start Plone, issue the following command. - -```shell -make start -``` - -The Plone backend server starts up and emits messages to the console. - -```console -2024-09-25 16:47:15,699 INFO [chameleon.config:39][MainThread] directory cache: //instance/var/cache. -2024-09-25 16:47:16,387 WARNING [ZODB.FileStorage:412][MainThread] Ignoring index for //instance/var/filestorage/Data.fs -2024-09-25 16:47:16,508 INFO [plone.restapi.patches:16][MainThread] PATCH: Disabled ZPublisher.HTTPRequest.ZopeFieldStorage.VALUE_LIMIT. This enables file uploads larger than 1MB. -2024-09-25 16:47:17,018 INFO [plone.volto:23][MainThread] Aliasing collective.folderish classes to plone.volto classes. -2024-09-25 16:47:17,760 INFO [Zope:42][MainThread] Ready to handle requests -Starting server in PID 20912. -2024-09-25 16:47:17,772 INFO [waitress:486][MainThread] Serving on http://[::1]:8080 -2024-09-25 16:47:17,772 INFO [waitress:486][MainThread] Serving on http://127.0.0.1:8080 -``` - -You can stop the site with {kbd}`ctrl-c`. - - -## Create Classic UI Plone site - -While the Plone backend server is running, open a browser and visit the following URL. - -http://localhost:8080 - -```{image} /_static/plone-classic-ui-landing-page.png -:class: figure -:alt: Plone Classic UI landing page -``` - -Click the button {guilabel}`Create Classic UI Plone site` to do exactly that. - -Use the username and password of `admin` to authenticate. -You will be redirected to the Create a Plone site page. - -```{image} /_static/plone-classic-ui-site-page.png -:class: figure -:alt: Plone Classic UI site page -``` - -Enter values for {guilabel}`Path identifier`, {guilabel}`Title`, {guilabel}`Language`, and {guilabel}`Default timezone`. -The default values are usually good. - -Click the button {guilabel}`Create Plone site`. - -You will be redirected to the Plone site you just created. diff --git a/docs/install/index.md b/docs/install/index.md index 1f8c95ce7..30ed2eaa6 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -1,59 +1,72 @@ --- myst: html_meta: - "description": "Install Plone 6" - "property=og:description": "Install Plone 6" - "property=og:title": "Install Plone 6" + "description": "Get started with Plone 6" + "property=og:description": "Get started with Plone 6" + "property=og:title": "Get started" "keywords": "Plone 6, install, overview" --- -(install-index-label)= +(get-started-label)= -# Install +# Get started -In this part of the documentation, you can find how to install Plone to either create a Plone project or contribute to a Plone package. -You can also {ref}`try a Plone demo `. +This part of the documentation helps you find the best way to get started with Plone, depending on what you want to do. +```{contents} I'd like to... +:local: true +``` + + +(get-started-try-plone-label)= + +## Try a Plone demo + +Choose a version to demo. + +- [Plone 6 with Volto frontend](https://demo.plone.org/) +- [Plone 6 with Classic UI](https://classic.demo.plone.org/login?came_from=/en) -(install-index-getting-started-label)= -## Get started +(get-started-install-label)= -Choose an option to get started with Plone. -If you are following a [Plone training](https://training.plone.org/), it should specify which option to choose. +## Install Plone -{doc}`create-project` -: This option is for developers who want to create a web application using the current **stable release** version of Plone with **Volto 17 or earlier** for the frontend. +First, choose a Plone frontend. [TODO: add link to explanation of how to choose] +(If you are following a [Plone training](https://training.plone.org/), it should specify which option to choose.) -{doc}`create-project-classic-ui` -: This option is for developers who want to create a web application using the current **stable release** version of Plone with **Classic UI** for the frontend. +{doc}`/admin-guide/install-cookieplone` +: This is the recommended way to install Plone for a new project with the Volto frontend. -{doc}`create-project-cookieplone` -: This option is for developers who want to create a web application using the latest **development release** version of Plone with **Volto 18 or later** for the frontend. - The "development" version also means "pre-release", and includes alpha and beta versions and release candidates. - It allows developers to work with the cutting edge of Plone. - A development version is not stable, and features may change with little notice. +{doc}`/admin-guide/install-buildout` +: This is one way to install Plone with the Classic UI. + Using Buildout will be the most familiar way for admins who have experience with Plone 3, 4, or 5. -{doc}`Contribute to a Plone package ` +{doc}`/admin-guide/install-pip` +: This is one way to install Plone with the Classic UI. + It provides a basic installation without many additional tools to help with development. + +{doc}`/admin-guide/install-plonestarter` +: This was the recommended way to install Plone 6.0 for a new project with the Volto frontend. + +{doc}`Install Plone as a contributor ` : This option is for developers who want to contribute to Plone and its packages. -(install-index-try-plone-label)= +(get-started-learn-more-label)= -## Try a Plone demo +## Learn more about Plone -Choose a version to demo. +The {doc}`/conceptual-guides/index` explain concepts to help you understand Plone. -- [Plone 6 with Volto frontend](https://demo.plone.org/) -- [Plone 6 with Classic UI](https://classic.demo.plone.org/login?came_from=/en) +The community has created a set of [Plone trainings](https://training.plone.org/) which are hosted separately from the documentation. -```{toctree} -:maxdepth: 2 -:hidden: true +(get-started-contribute-label)= -create-project -create-project-classic-ui -create-project-cookieplone -containers/index -``` +## Contribute to Plone + +See the {doc}`Contributor Guide ` to learn how to participate in the Plone community and contribute to our open source software. + + +(install-index-getting-started-label)= diff --git a/docs/manage/backend.md b/docs/manage/backend.md index 8f24599d2..a8a16d59d 100644 --- a/docs/manage/backend.md +++ b/docs/manage/backend.md @@ -12,7 +12,7 @@ myst: # Manage Plone backend This part of the documentation describes how to perform common management tasks in the Plone backend. -This chapter assumes you have previously followed {doc}`/install/create-project`. +This chapter assumes you have previously followed {doc}`/admin-guide/install-plonestarter`. ## Manage add-ons and packages From 2603852183bed15299396ce4c523f2a83f5247a0 Mon Sep 17 00:00:00 2001 From: David Glick Date: Sun, 27 Oct 2024 15:14:41 -0700 Subject: [PATCH 02/29] Add run-plone to admin guide --- docs/admin-guide/index.md | 1 + docs/admin-guide/run-plone.md | 93 +++++++++++++++++++++++++++++++++++ 2 files changed, 94 insertions(+) create mode 100644 docs/admin-guide/run-plone.md diff --git a/docs/admin-guide/index.md b/docs/admin-guide/index.md index 0d701262e..92302425d 100644 --- a/docs/admin-guide/index.md +++ b/docs/admin-guide/index.md @@ -28,6 +28,7 @@ install-plonestarter :caption: Operate :maxdepth: 1 +run-plone upgrade ``` diff --git a/docs/admin-guide/run-plone.md b/docs/admin-guide/run-plone.md new file mode 100644 index 000000000..ca341af06 --- /dev/null +++ b/docs/admin-guide/run-plone.md @@ -0,0 +1,93 @@ +--- +myst: + html_meta: + "description": "Run Plone" + "property=og:description": "Run Plone" + "property=og:title": "Run Plone" + "keywords": "Plone 6, run, start, command" +--- + +(run-plone-label)= + +# Run Plone + +This chapter shows the commands to run Plone after it is installed. + +There are different commands to run Plone, depending on which method you used to install Plone. + +## Run Plone in foreground mode + +Running Plone in foreground mode will show output in the terminal. This is recommended while developing a Plone site. + +with Cookieplone: +: ```shell + make backend-start + ``` + +with Buildout: +: ```shell + bin/instance fg + ``` + +with pip: +: ```shell + bin/runwsgi instance/etc/zope.ini + ``` + +with `cookiecutter-plone-starter`: +: ```shell + make start-backend + ``` + +## Run Volto + +If you are using the Volto frontend, you need to run the frontend in a separate process. + +with Cookieplone: +: ```shell + make frontend-start + ``` + +with `cookiecutter-plone-starter`: +: ```shell + make start-frontend + ``` + +## Start Plone as a background service + +with Buildout: +: ```shell + bin/instance start + ``` + +## Stop Plone as a background service + +with Buildout: +: ```shell + bin/instance stop + ``` + +## Run a debug console + +The debug console gives you a Python prompt with the Plone site's configuration loaded. +Use this for troubleshooting. + +with Cookieplone: +: ```shell + make -C backend console + ``` + +with Buildout: +: ```shell + bin/instance debug + ``` + +with pip: +: ```shell + bin/zconsole debug instance/etc/zope.ini + ``` + +with `cookiecutter-plone-starter`: +: ```shell + make -C backend debug + ``` From 323429e1b54fb5fd4f5dab199000dbf23d99caf0 Mon Sep 17 00:00:00 2001 From: David Glick Date: Sun, 27 Oct 2024 15:17:15 -0700 Subject: [PATCH 03/29] Add info about how to stop --- docs/admin-guide/run-plone.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/admin-guide/run-plone.md b/docs/admin-guide/run-plone.md index ca341af06..728daaee6 100644 --- a/docs/admin-guide/run-plone.md +++ b/docs/admin-guide/run-plone.md @@ -39,6 +39,9 @@ with `cookiecutter-plone-starter`: make start-backend ``` +For any of these commands, press {kbd}`ctrl-c` to stop the process. + + ## Run Volto If you are using the Volto frontend, you need to run the frontend in a separate process. @@ -53,6 +56,9 @@ with `cookiecutter-plone-starter`: make start-frontend ``` +For any of these commands, press {kbd}`ctrl-c` to stop the process. + + ## Start Plone as a background service with Buildout: @@ -91,3 +97,5 @@ with `cookiecutter-plone-starter`: : ```shell make -C backend debug ``` + +For any of these commands, press {kbd}`ctrl-d` to stop the process. From 2645edd72fa9a3688c58f6f2414f279f7e873606 Mon Sep 17 00:00:00 2001 From: David Glick Date: Sun, 27 Oct 2024 16:08:31 -0700 Subject: [PATCH 04/29] Add chapter about backend add-ons to admin guide --- docs/admin-guide/add-ons.md | 200 ++++++++++++++++++++++++++++++++++++ docs/admin-guide/index.md | 1 + 2 files changed, 201 insertions(+) create mode 100644 docs/admin-guide/add-ons.md diff --git a/docs/admin-guide/add-ons.md b/docs/admin-guide/add-ons.md new file mode 100644 index 000000000..61d8b532a --- /dev/null +++ b/docs/admin-guide/add-ons.md @@ -0,0 +1,200 @@ +--- +myst: + html_meta: + "description": "Install Plone Add-ons" + "property=og:description": "Install Plone Add-ons" + "property=og:title": "Install Plone Add-ons" + "keywords": "Plone 6, addon, add-on, package, plugin, extension, install" +--- + +(install-plone-addons-label)= + +# Install Plone Add-ons + +This chapter explains how to install {term}`add-ons ` as Python packages to extend the functionality of the Plone backend or Classic UI. + +```{note} +The Volto frontend has its own system of add-ons using Node.js packages. See {doc}`/volto/addons/index`. +``` + +## with Cookieplone + +Use the following instructions if you installed Plone with Cookieplone or `cookiecutter-plone-starter`. + +### Install an add-on + +Add a line with the name of your add-on in `backend/requirements.txt`. +This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/). + +``` +collective.easyform==4.2.1 +``` + +```{tip} +Including the add-on version ensures that it won't accidentally get upgraded in the future. +``` + +Also add the add-on to `zcml_package_includes` in {file}`backend/instance.yaml` to make sure its configuration will be loaded: + +```yaml +default_context: + zcml_package_includes: project_title, collective.easyform +``` + +Stop the backend with {kbd}`ctrl-c`. + +To actually download and install the new add-on, run: + +```shell +make backend-build +``` + +```{note} +If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead.` +``` + +Now restart the backend. + +In your web browser, and assuming you are currently logged in as `admin`, visit the URL http://localhost:8080/Plone/prefs_install_products_form. + +Then click the {guilabel}`Install` button next to your add-on to complete installation of the add-on. + +Some add-ons have configuration options. +To configure such add-ons, return to the {guilabel}`Site Setup` control panel. +At the bottom of the page, you should see the heading {guilabel}`Add-on Configuration`, and a control panel to configure the add-on that you just installed. + + +### Install an add-on from source + +An add-on can be installed from a source control system such as GitHub. + +Add a line with the name of your add-on in `backend/requirements.txt`. +This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/). + +``` +collective.easyform +``` + +```{note} +When installing an add-on from source, it's best to not pin a version, to make sure we use the version that's currently available in the source control system. +``` + +Also add the add-on to `zcml_package_includes` in {file}`backend/instance.yaml` to make sure its configuration will be loaded: + +```yaml +default_context: + zcml_package_includes: project_title, collective.easyform +``` + +Finally, add the package's source to {file}`mx.ini`: + +```cfg +[collective.easyform] +url=git@github.com:collective/collective.easyform.git +branch=dev-branch-name +extras=test +``` + +```{seealso} +The {file}`mx.ini` file configures a tool called {term}`mxdev`. +See the [documentation of `mxdev` in its README.md](https://github.com/mxstack/mxdev/blob/main/README.md) for complete information. +``` + +Stop the backend with {kbd}`ctrl-c`. + +To actually download and install the new add-on, run: + +```shell +make backend-build +``` + +```{note} +If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead.` +``` + +Now restart the backend. + +In your web browser, and assuming you are currently logged in as `admin`, visit the URL http://localhost:8080/Plone/prefs_install_products_form. +An upgrade step might need to be performed in the Plone control panel. +Follow the upgrade information, if present. +Else click the {guilabel}`Install` button to complete installation of the add-on. + + +## with Buildout + +Use the following instructions if you installed Plone with Buildout. + +### Install an add-on + +Update {file}`buildout.cfg`. +This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/). + +```cfg +[buildout] +extends = + https://dist.plone.org/release/6-latest/versions.cfg + +parts = + instance + +[instance] +recipe = plone.recipe.zope2instance +user = admin:admin +http-address = 8080 +eggs = + Plone + collective.easyform + +[versions] +collective.easyform = 4.2.1 +``` + +```{tip} +Including the add-on version ensures that it won't accidentally get upgraded in the future. +``` + +To actually download and install the new add-on, run: + +```shell +bin/buildout +``` + +### Install an add-on from source + +An add-on can be installed from a source control system such as GitHub. + +Update {file}`buildout.cfg`. +This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/). + +```cfg +[buildout] +extends = + https://dist.plone.org/release/6-latest/versions.cfg +extensions = mr.developer +auto-checkout = + collective.easyform + +parts = + instance + +[instance] +recipe = plone.recipe.zope2instance +user = admin:admin +http-address = 8080 +eggs = + Plone + collective.easyform + +[sources] +collective.easyform = git https://github.com/collective/collective.easyform.git +``` + +To actually download and install the new add-on, run: + +```shell +bin/buildout +``` + +```{seealso} +This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension. +``` diff --git a/docs/admin-guide/index.md b/docs/admin-guide/index.md index 92302425d..dbc026aac 100644 --- a/docs/admin-guide/index.md +++ b/docs/admin-guide/index.md @@ -29,6 +29,7 @@ install-plonestarter :maxdepth: 1 run-plone +add-ons upgrade ``` From af5ced1da17241d0f2556431141a166651e49f6d Mon Sep 17 00:00:00 2001 From: David Glick Date: Sun, 27 Oct 2024 16:43:09 -0700 Subject: [PATCH 05/29] Add overrides & zope config, remove old manage section --- docs/admin-guide/add-ons.md | 4 + docs/admin-guide/configure-zope.md | 33 ++++ docs/admin-guide/index.md | 6 +- docs/admin-guide/override-core.md | 167 ++++++++++++++++ docs/index.md | 1 - docs/manage/backend.md | 299 ----------------------------- docs/manage/frontend.md | 18 -- docs/manage/index.md | 20 -- 8 files changed, 206 insertions(+), 342 deletions(-) create mode 100644 docs/admin-guide/configure-zope.md create mode 100644 docs/admin-guide/override-core.md delete mode 100644 docs/manage/backend.md delete mode 100644 docs/manage/frontend.md delete mode 100644 docs/manage/index.md diff --git a/docs/admin-guide/add-ons.md b/docs/admin-guide/add-ons.md index 61d8b532a..c6c8e6fb3 100644 --- a/docs/admin-guide/add-ons.md +++ b/docs/admin-guide/add-ons.md @@ -159,6 +159,8 @@ To actually download and install the new add-on, run: bin/buildout ``` +Then restart your instance. + ### Install an add-on from source An add-on can be installed from a source control system such as GitHub. @@ -195,6 +197,8 @@ To actually download and install the new add-on, run: bin/buildout ``` +Then restart your instance. + ```{seealso} This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension. ``` diff --git a/docs/admin-guide/configure-zope.md b/docs/admin-guide/configure-zope.md new file mode 100644 index 000000000..0f05786ca --- /dev/null +++ b/docs/admin-guide/configure-zope.md @@ -0,0 +1,33 @@ +--- +myst: + html_meta: + "description": "Configure Zope options" + "property=og:description": "Configure Zope options" + "property=og:title": "Configure Zope" + "keywords": "Plone 6, Zope, instance, app server, config, cookiecutter-zope-instance" +--- + +(configure-zope-label)= + +# Configure Zope + +Plone runs in an application server called {term}`Zope`. + +You can configure your Zope instance's options, including the following. + +* persistent storage: blobs, direct filestorage, relation database, ZEO, and so on +* ports +* threads +* cache +* logging +* debugging and profiling for development + +## with Cookieplone + +If you installed Plone using Cookieplone, `cookiecutter-plone-starter`, or pip, then Zope is configured using {term}`cookiecutter-zope-instance`. +For a complete list of features, usage, and options, read [`cookiecutter-zope-instance`'s README](https://github.com/plone/cookiecutter-zope-instance#readme). + +## with Buildout + +If you installed Plone using Buildout, then Zope is configured using `plone.recipe.zope2instance`. +For a complete list of features, usage, and options, read [`plone.recipe.zope2instance`'s README](https://pypi.org/project/plone.recipe.zope2instance/). diff --git a/docs/admin-guide/index.md b/docs/admin-guide/index.md index dbc026aac..3d19b17f3 100644 --- a/docs/admin-guide/index.md +++ b/docs/admin-guide/index.md @@ -29,7 +29,9 @@ install-plonestarter :maxdepth: 1 run-plone +configure-zope add-ons +override-core upgrade ``` @@ -39,7 +41,3 @@ upgrade containers/index ``` - - -To do: -- move and update Manage section diff --git a/docs/admin-guide/override-core.md b/docs/admin-guide/override-core.md new file mode 100644 index 000000000..38f80abd4 --- /dev/null +++ b/docs/admin-guide/override-core.md @@ -0,0 +1,167 @@ +--- +myst: + html_meta: + "description": "Override core Plone packages" + "property=og:description": "Override core Plone packages" + "property=og:title": "Override core Plone packages" + "keywords": "Plone 6, core, package, version, override" +--- + +(override-core-plone-packages-label)= + +# Override core Plone packages + +Plone includes a lot of Python packages. +Sometimes it is necessary to override one or more package versions in order to fix a bug. + + +## with Cookieplone + +Use the following instructions if you installed Plone with Cookieplone or `cookiecutter-plone-starter`. + +### Override a core Plone package + +Add a version override to {file}`mx.ini`. +This example uses `plone.api`. + +``` +[settings] +version-overrides = + plone.api==2.0.0a3 +``` + +```{seealso} +The {file}`mx.ini` file configures a tool called {term}`mxdev`. +For an explanation of why Plone uses `mxdev`, see {ref}`manage-backend-python-packages-label`. +``` + +Stop the backend with {kbd}`ctrl-c`. + +To actually download and install the new package version, run: + +```shell +make backend-build +``` + +```{note} +If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead.` +``` + +Now restart the backend. + + +### Install a core Plone package from source + +`mxdev` can also be used to install core Plone packages from a source control system such as GitHub. + +Add the Plone package you want to check out in {file}`mx.ini`. +This example uses `plone.restapi`. + +```cfg +[plone.restapi] +url = git@github.com:plone/plone.restapi.git +branch = main +extras = test +``` + +Stop the backend with {kbd}`ctrl-c`. + +To actually download and install the new package version, run: + +```shell +make backend-build +``` + +```{note} +If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead.` +``` + +Now restart the backend. + + +## with Buildout + +Use the following instructions if you installed Plone with Buildout. + +### Override a core Plone package + +Update {file}`buildout.cfg`. +This example uses `plone.api`. + +```cfg +[buildout] +extends = + https://dist.plone.org/release/6-latest/versions.cfg + +parts = + instance + +[instance] +recipe = plone.recipe.zope2instance +user = admin:admin +http-address = 8080 +eggs = + Plone + +[versions] +plone.api = 2.0.0a3 +``` + +```{note} +The version pins specified in the `[versions]` section will take precedence over the pins inherited from `https://dist.plone.org/release/6-latest/versions.cfg`. +``` + +To actually download and install the new package version, run: + +```shell +bin/buildout +``` + +Then restart your instance. + + +### Install a core Plone package from source + +A core Plone package can be installed from a source control system such as GitHub. + +Update {file}`buildout.cfg`. +This example uses `plone.restapi`. + +```cfg +[buildout] +extends = + https://dist.plone.org/release/6-latest/versions.cfg +extensions = mr.developer +auto-checkout = + plone.restapi + +parts = + instance + +[instance] +recipe = plone.recipe.zope2instance +user = admin:admin +http-address = 8080 +eggs = + Plone + +[sources] +plone.restapi = git https://github.com/plone/plone.restapi.git + +[versions] +plone.restapi = +``` + +```{tip} +Setting an empty version ensures that the copy of `plone.restapi` from source control will be used, instead of the version pin inherited from https://dist.plone.org/release/6-latest/versions.cfg. +``` + +To actually download and install the new add-on, run: + +```shell +bin/buildout +``` + +```{seealso} +This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension. +``` diff --git a/docs/index.md b/docs/index.md index f76575d8a..9f4594162 100644 --- a/docs/index.md +++ b/docs/index.md @@ -33,7 +33,6 @@ Read the [documentation for the previous version, Plone 5](https://5.docs.plone. overview/index install/index admin-guide/index -manage/index deployment/index volto/index classic-ui/index diff --git a/docs/manage/backend.md b/docs/manage/backend.md deleted file mode 100644 index a8a16d59d..000000000 --- a/docs/manage/backend.md +++ /dev/null @@ -1,299 +0,0 @@ ---- -myst: - html_meta: - "description": "Manage Plone backend" - "property=og:description": "Manage Plone backend" - "property=og:title": "Manage Plone backend" - "keywords": "Plone 6, manage, backend, add-ons, packages, mxdev" ---- - -(manage-plone-backend-label)= - -# Manage Plone backend - -This part of the documentation describes how to perform common management tasks in the Plone backend. -This chapter assumes you have previously followed {doc}`/admin-guide/install-plonestarter`. - - -## Manage add-ons and packages - -Plone uses `mxdev` to manage packages and constraints. - -```{seealso} -For an explanation of why Plone uses `mxdev`, see {ref}`manage-backend-python-packages-label`. -``` - - -(mxdev-usage-overview-label)= - -### `mxdev` usage overview - -The default set of files for `mxdev` is shown below. -They are located in the `backend` directory of your project. - -{file}`requirements.txt` - -```ini --c constraints.txt --e src/project_title - -zope.testrunner - -# Add required add-ons -# collective.easyform -``` - -{file}`constraints.txt` - -```ini --c https://dist.plone.org/release/{PLONE_BACKEND_PATCH_VERSION}/constraints.txt -``` - -{file}`mx.ini` - -```ini -; This is a mxdev configuration file -; it can be used to override versions of packages already defined in the -; constraints files and to add new packages from VCS like git. -; to learn more about mxdev visit https://pypi.org/project/mxdev/ - -[settings] -; example how to override a package version -; version-overrides = -; example.package==2.1.0a2 - -; example section to use packages from git -; [example.contenttype] -; url = https://github.com/collective/example.contenttype.git -; pushurl = git@github.com:collective/example.contenttype.git -; extras = test -; branch = feature-7 -``` - -You can edit these three files in your project as you need. -Then you can generate package requirements and constraints files, and then install those packages, with one command. - -```shell -make build-backend -``` - -`make build-backend` invokes `mxdev`, which generates the files {file}`requirements-mxdev.txt` and {file}`constraints-mxdev.txt`. -It then invokes `pip` to install packages with the new requirements file. - -To reload the packages, stop your Plone site with {kbd}`ctrl-c`, and start it with the following command. - -```shell -make start-backend -``` - -```{seealso} -See the [documentation of `mxdev` in its README.md](https://github.com/mxstack/mxdev/blob/main/README.md) for complete information. -``` - - -(manage-add-an-add-on)= - -### Add an add-on - -Add a line with the name of your add-on in `requirements.txt`. -This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/). - -``` -collective.easyform -``` - -Add it to {file}`instance.yaml` to let Zope know that this add-on should be loaded: - -```yaml -default_context: - zcml_package_includes: project_title, collective.easyform -``` - -Stop the backend with {kbd}`ctrl-c`. -Then apply your changes and start the backend. -You do not need to stop the frontend. - -```shell -make build-backend -make start-backend -``` - -In your web browser, and assuming you are currently logged in as `admin`, visit the URL http://localhost:8080/Plone/prefs_install_products_form. - -Then click the {guilabel}`Install` button next to your add-on to complete installation of the add-on. - -Some add-ons have configuration options. -To configure such add-ons, return to the {guilabel}`Site Setup` control panel. -At the bottom of the page, you should see the heading {guilabel}`Add-on Configuration`, and a control panel to configure the add-on that you just installed. - - -(manage-pin-the-version-of-an-add-on)= - -### Pin the version of an add-on - -Pin the version in {file}`constraints.txt`. - -``` -collective.easyform==3.1.0 -``` - -Add the add-on to {file}`requirements.txt`: - -``` -collective.easyform -``` - -Add it to {file}`instance.yaml` to let Zope know that this add-on should be loaded: - -```yaml -default_context: - zcml_package_includes: project_title, collective.easyform -``` - -Stop the backend with {kbd}`ctrl-c`. -Then apply your changes and start the backend. - -```shell -make build-backend -make start-backend -``` - -In your web browser, and assuming you are currently logged in as `admin`, visit the URL http://localhost:8080/Plone/prefs_install_products_form. -An upgrade step might need to be performed in the Plone control panel. -Follow the upgrade information, if present. -Else click the {guilabel}`Install` button to complete installation of the add-on. - - -(manage-check-out-an-add-on)= - -### Check out an add-on - -Add the add-on in {file}`requirements.txt`: - -``` -collective.easyform -``` - -In {file}`mx.ini`, specify the information to check out the add-on: - -```ini -[collective.easyform] -url=git@github.com:collective/collective.easyform.git -branch=dev-branch-name -extras=test -``` - -Add it to {file}`instance.yaml` to let Zope know that this add-on should be loaded: - -```yaml -default_context: - zcml_package_includes: project_title, collective.easyform -``` - -Stop the backend with {kbd}`ctrl-c`. -Then apply your changes and start the backend. - -```shell -make build-backend -make start-backend -``` - -In your web browser, and assuming you are currently logged in as `admin`, visit the URL http://localhost:8080/Plone/prefs_install_products_form. -An upgrade step might need to be performed in the Plone control panel. -Follow the upgrade information, if present. -Else click the {guilabel}`Install` button to complete installation of the add-on. - - -(manage-pin-the-version-of-a-plone-package-against-constraints-label)= - -### Pin the version of a Plone package against constraints - -A version can **not** be pinned in `constraints.txt` when the package is mentioned in the constraints of Plone. -Any other package version could be pinned in `constraints.txt`. - -Pin the version of a Plone package in {file}`mx.ini`: - -```ini -[settings] -# constraints of Plone packages -version-overrides = - plone.api>=2.0.0a3 -``` - -Apply your changes and restart backend: - -```shell -make build-backend -make start-backend -``` - -In your web browser, and assuming you are currently logged in as `admin`, visit the URL http://localhost:8080/Plone/prefs_install_products_form. -An upgrade step might need to be performed in the Plone control panel. -Follow the upgrade information, if present. - - -(manage-checkout-a-plone-package-label)= - -### Check out a Plone package - -This section covers how to check out a Plone Core package for development. - -Add the Plone package you want to check out in {file}`mx.ini`. - -```ini -[plone.restapi] -url = git@github.com:plone/plone.restapi.git -branch = main -extras = test -``` - -Stop the backend with {kbd}`ctrl-c`. -Then apply your changes and start the backend. - -```shell -make build-backend -make start-backend -``` - -In your web browser, and assuming you are currently logged in as `admin`, visit the URL http://localhost:8080/Plone/prefs_install_products_form. -An upgrade step might need to be performed in the Plone control panel. -Follow the upgrade information, if present. - - -(manage-build-and-start-your-instance-label)= - -### Build and start your instance - -Whenever you make changes to your backend configuration—for example, install an add-on, or override a Plone core package—then a build and restart is needed. -First stop your Zope instance/Plone site with {kbd}`ctrl-c`. -Then build and run the Plone backend. - -```shell -make build-backend -make start-backend -``` - -In a web browser, visit http://localhost:8080/ to see that Plone is running. - -Your instance is running in the foreground. - -```{seealso} -For an explanation of the command `make build-backend`, see {doc}`/conceptual-guides/make-build-backend-walk-through`. -``` - - -(manage-configuration-with-cookiecutter-zope-instance-label)= - -## Configuration with `cookiecutter-zope-instance` - -You can configure your instance's options, including the following. - -- persistent storage: blobs, direct filestorage, relational database, ZEO, and so on -- ports -- threads -- cache -- debugging and profiling for development - -```{seealso} -For a complete list of features, usage, and options, read [`cookiecutter-zope-instance`'s `README.rst`](https://github.com/plone/cookiecutter-zope-instance#readme). -``` diff --git a/docs/manage/frontend.md b/docs/manage/frontend.md deleted file mode 100644 index 9d3c275c9..000000000 --- a/docs/manage/frontend.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -myst: - html_meta: - "description": "Manage Plone frontend" - "property=og:description": "Manage Plone frontend" - "property=og:title": "Manage Plone frontend" - "keywords": "Plone 6, manage, frontend, add-ons, packages" ---- - -(manage-plone-frontend-label)= - -# Manage Plone frontend - -This part of the documentation describes how to perform common management tasks in the Plone frontend. - -```{seealso} -{doc}`/volto/addons/index` -``` diff --git a/docs/manage/index.md b/docs/manage/index.md deleted file mode 100644 index 4e7fb946e..000000000 --- a/docs/manage/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -myst: - html_meta: - "description": "Manage add-ons, packages, and processes in Plone" - "property=og:description": "Manage add-ons, packages, and processes in Plone" - "property=og:title": "Manage add-ons, packages, and processes in Plone" - "keywords": "Plone 6, manage, backend, frontend, Volto, Classic UI, add-ons, packages, processes, cookiecutter, Zope" ---- - -# Manage Plone - -This part of the documentation describes how to perform common management tasks in Plone. - - -```{toctree} -:maxdepth: 2 - -backend -frontend -``` From 4b688a79626dba325c4602575483ab95cff16aaf Mon Sep 17 00:00:00 2001 From: David Glick Date: Mon, 28 Oct 2024 17:31:49 -0700 Subject: [PATCH 06/29] move docs back to their old paths to avoid need for redirects --- docs/admin-guide/index.md | 8 ++++---- docs/conf.py | 6 +----- .../containers/examples/haproxy-plone-zeo.md | 0 .../{admin-guide => install}/containers/examples/index.md | 0 .../containers/examples/nginx-plone.md | 0 .../containers/examples/nginx-volto-plone-postgresql.md | 0 .../containers/examples/nginx-volto-plone-zeo.md | 0 .../containers/examples/nginx-volto-plone.md | 0 .../containers/examples/traefik-volto-plone-varnish.md | 0 .../{admin-guide => install}/containers/images/backend.md | 0 .../containers/images/frontend.md | 0 docs/{admin-guide => install}/containers/images/index.md | 0 docs/{admin-guide => install}/containers/images/zeo.md | 0 docs/{admin-guide => install}/containers/index.md | 0 .../create-project-cookieplone.md} | 0 .../install-plonestarter.md => install/create-project.md} | 0 docs/install/index.md | 4 ++-- docs/{admin-guide/upgrade.md => upgrade/index.md} | 0 18 files changed, 7 insertions(+), 11 deletions(-) rename docs/{admin-guide => install}/containers/examples/haproxy-plone-zeo.md (100%) rename docs/{admin-guide => install}/containers/examples/index.md (100%) rename docs/{admin-guide => install}/containers/examples/nginx-plone.md (100%) rename docs/{admin-guide => install}/containers/examples/nginx-volto-plone-postgresql.md (100%) rename docs/{admin-guide => install}/containers/examples/nginx-volto-plone-zeo.md (100%) rename docs/{admin-guide => install}/containers/examples/nginx-volto-plone.md (100%) rename docs/{admin-guide => install}/containers/examples/traefik-volto-plone-varnish.md (100%) rename docs/{admin-guide => install}/containers/images/backend.md (100%) rename docs/{admin-guide => install}/containers/images/frontend.md (100%) rename docs/{admin-guide => install}/containers/images/index.md (100%) rename docs/{admin-guide => install}/containers/images/zeo.md (100%) rename docs/{admin-guide => install}/containers/index.md (100%) rename docs/{admin-guide/install-cookieplone.md => install/create-project-cookieplone.md} (100%) rename docs/{admin-guide/install-plonestarter.md => install/create-project.md} (100%) rename docs/{admin-guide/upgrade.md => upgrade/index.md} (100%) diff --git a/docs/admin-guide/index.md b/docs/admin-guide/index.md index 3d19b17f3..8d8dd9907 100644 --- a/docs/admin-guide/index.md +++ b/docs/admin-guide/index.md @@ -18,10 +18,10 @@ In this part of the documentation, you can find how to install, operate, configu :caption: Install :maxdepth: 1 -install-cookieplone +/install/create-project-cookieplone install-buildout install-pip -install-plonestarter +/install/create-project ``` ```{toctree} @@ -32,12 +32,12 @@ run-plone configure-zope add-ons override-core -upgrade +/upgrade/index ``` ```{toctree} :maxdepth: 1 :caption: Deploy -containers/index +/install/containers/index ``` diff --git a/docs/conf.py b/docs/conf.py index ca61b9e21..43fd357ff 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -245,12 +245,8 @@ "contributing/plone-api": "/plone.api/contribute/index.html", "contributing/plone-restapi": "/plone.restapi/docs/source/contributing/index.html", "contributing/volto": "/volto/contributing/index.html", - "install/containers/index": "/admin-guide/containers/index.html", - "install/create-project-cookieplone": "/admin-guide/install-cookieplone.html", - "install/create-project": "/admin-guide/install-plonestarter.html", - "install/install-from-packages": "/admin-guide/install-cookieplone.html", + "install/install-from-packages": "/install/create-project.html", "manage/frontend": "/volto/addons/index.html", - "upgrade/index": "/admin-guide/upgrade.html", } diff --git a/docs/admin-guide/containers/examples/haproxy-plone-zeo.md b/docs/install/containers/examples/haproxy-plone-zeo.md similarity index 100% rename from docs/admin-guide/containers/examples/haproxy-plone-zeo.md rename to docs/install/containers/examples/haproxy-plone-zeo.md diff --git a/docs/admin-guide/containers/examples/index.md b/docs/install/containers/examples/index.md similarity index 100% rename from docs/admin-guide/containers/examples/index.md rename to docs/install/containers/examples/index.md diff --git a/docs/admin-guide/containers/examples/nginx-plone.md b/docs/install/containers/examples/nginx-plone.md similarity index 100% rename from docs/admin-guide/containers/examples/nginx-plone.md rename to docs/install/containers/examples/nginx-plone.md diff --git a/docs/admin-guide/containers/examples/nginx-volto-plone-postgresql.md b/docs/install/containers/examples/nginx-volto-plone-postgresql.md similarity index 100% rename from docs/admin-guide/containers/examples/nginx-volto-plone-postgresql.md rename to docs/install/containers/examples/nginx-volto-plone-postgresql.md diff --git a/docs/admin-guide/containers/examples/nginx-volto-plone-zeo.md b/docs/install/containers/examples/nginx-volto-plone-zeo.md similarity index 100% rename from docs/admin-guide/containers/examples/nginx-volto-plone-zeo.md rename to docs/install/containers/examples/nginx-volto-plone-zeo.md diff --git a/docs/admin-guide/containers/examples/nginx-volto-plone.md b/docs/install/containers/examples/nginx-volto-plone.md similarity index 100% rename from docs/admin-guide/containers/examples/nginx-volto-plone.md rename to docs/install/containers/examples/nginx-volto-plone.md diff --git a/docs/admin-guide/containers/examples/traefik-volto-plone-varnish.md b/docs/install/containers/examples/traefik-volto-plone-varnish.md similarity index 100% rename from docs/admin-guide/containers/examples/traefik-volto-plone-varnish.md rename to docs/install/containers/examples/traefik-volto-plone-varnish.md diff --git a/docs/admin-guide/containers/images/backend.md b/docs/install/containers/images/backend.md similarity index 100% rename from docs/admin-guide/containers/images/backend.md rename to docs/install/containers/images/backend.md diff --git a/docs/admin-guide/containers/images/frontend.md b/docs/install/containers/images/frontend.md similarity index 100% rename from docs/admin-guide/containers/images/frontend.md rename to docs/install/containers/images/frontend.md diff --git a/docs/admin-guide/containers/images/index.md b/docs/install/containers/images/index.md similarity index 100% rename from docs/admin-guide/containers/images/index.md rename to docs/install/containers/images/index.md diff --git a/docs/admin-guide/containers/images/zeo.md b/docs/install/containers/images/zeo.md similarity index 100% rename from docs/admin-guide/containers/images/zeo.md rename to docs/install/containers/images/zeo.md diff --git a/docs/admin-guide/containers/index.md b/docs/install/containers/index.md similarity index 100% rename from docs/admin-guide/containers/index.md rename to docs/install/containers/index.md diff --git a/docs/admin-guide/install-cookieplone.md b/docs/install/create-project-cookieplone.md similarity index 100% rename from docs/admin-guide/install-cookieplone.md rename to docs/install/create-project-cookieplone.md diff --git a/docs/admin-guide/install-plonestarter.md b/docs/install/create-project.md similarity index 100% rename from docs/admin-guide/install-plonestarter.md rename to docs/install/create-project.md diff --git a/docs/install/index.md b/docs/install/index.md index 30ed2eaa6..84c4707db 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -35,7 +35,7 @@ Choose a version to demo. First, choose a Plone frontend. [TODO: add link to explanation of how to choose] (If you are following a [Plone training](https://training.plone.org/), it should specify which option to choose.) -{doc}`/admin-guide/install-cookieplone` +{doc}`create-project-cookieplone` : This is the recommended way to install Plone for a new project with the Volto frontend. {doc}`/admin-guide/install-buildout` @@ -46,7 +46,7 @@ First, choose a Plone frontend. [TODO: add link to explanation of how to choose] : This is one way to install Plone with the Classic UI. It provides a basic installation without many additional tools to help with development. -{doc}`/admin-guide/install-plonestarter` +{doc}`create-project` : This was the recommended way to install Plone 6.0 for a new project with the Volto frontend. {doc}`Install Plone as a contributor ` diff --git a/docs/admin-guide/upgrade.md b/docs/upgrade/index.md similarity index 100% rename from docs/admin-guide/upgrade.md rename to docs/upgrade/index.md From 87562cf93186ee049813fa4b8d639ea68931e1c4 Mon Sep 17 00:00:00 2001 From: David Glick Date: Wed, 30 Oct 2024 16:06:35 -0700 Subject: [PATCH 07/29] fixes --- docs/conceptual-guides/make-build-backend-walk-through.md | 4 ++-- docs/conceptual-guides/package-management.md | 2 +- docs/install/containers/index.md | 2 +- docs/install/create-project.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/conceptual-guides/make-build-backend-walk-through.md b/docs/conceptual-guides/make-build-backend-walk-through.md index 3c0ce4347..859852ac8 100644 --- a/docs/conceptual-guides/make-build-backend-walk-through.md +++ b/docs/conceptual-guides/make-build-backend-walk-through.md @@ -11,7 +11,7 @@ myst: # `make build-backend` details -This chapter assumes you have previously followed {doc}`/admin-guide/install-plonestarter`. +This chapter assumes you have previously followed {doc}`/install/create-project`. The `Makefile` at the root of your project invokes commands in `backend/Makefile`. Here are excerpts from `backend/Makefile` to show details of the `make build-backend` command. @@ -55,4 +55,4 @@ The command `make build-backend`: - This generates the `mxdev` files as described above in {ref}`mxdev-usage-overview-label`. - Installs Plone core packages and add-ons from the files generated by `mxdev`. -You can configure your Zope instance as described in the section {ref}`manage-configuration-with-cookiecutter-zope-instance-label`. +You can configure your Zope instance as described in the section {doc}`/admin-guide/configure-zope`. diff --git a/docs/conceptual-guides/package-management.md b/docs/conceptual-guides/package-management.md index 7e19bf175..baaef4a35 100644 --- a/docs/conceptual-guides/package-management.md +++ b/docs/conceptual-guides/package-management.md @@ -53,7 +53,7 @@ The generated files indicate from where the constraints were fetched, and commen You or your development tools, such as GNU Make, must perform that step. ```{seealso} -{doc}`/manage/backend` +{doc}`/admin-guide/add-ons` ``` diff --git a/docs/install/containers/index.md b/docs/install/containers/index.md index d5475b532..6c925d4a9 100644 --- a/docs/install/containers/index.md +++ b/docs/install/containers/index.md @@ -14,7 +14,7 @@ myst: The Plone 6 images have all the system requirements, prerequisites, and Plone 6 already installed, except those requirements needed for running the container engine itself. Using containers is the easiest way to deploy Plone 6. -Containers may also be used when {doc}`creating a Plone project `. +Containers may also be used when {doc}`creating a Plone project `. The Plone 6 container images are compliant with the [Open Container Initiative (OCI)](https://opencontainers.org/). They should work with any OCI-compliant container engine for developing, managing, and running Plone 6 images. diff --git a/docs/install/create-project.md b/docs/install/create-project.md index 7e8a25317..2d8a46500 100644 --- a/docs/install/create-project.md +++ b/docs/install/create-project.md @@ -14,7 +14,7 @@ myst: This chapter describes how you can create a web application using the {term}`cookiecutter-plone-starter` template. -```{deprecated} +```{deprecated} Plone 6.1 & Volto 18 This way of installing Plone is now deprecated. It was the recommended way to start a new Plone project with **Plone 6.0** and **Volto 17 or earlier**. For other installation options, see {ref}`get-started-install-label`. From 50873f107ca74d964399defee895b4ace7bdd223 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 1 Nov 2024 06:14:08 -0700 Subject: [PATCH 08/29] Fix duplicate glossary entry --- docs/glossary.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/glossary.md b/docs/glossary.md index 1a8c8a9a3..8baf0d4d1 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -296,7 +296,6 @@ TC39 They established a [process](https://tc39.es/process-document/) where the proposals are discussed, developed, and eventually approved (or dropped). The process has five Stages (0 to 4) where reaching the Stage 4 means the proposal is finished, and it becomes part of the JavaScript specification. -mrs-developer `mrs-developer` Also called "missdev", a tool similar to buildout's `mr.developer`. It automatically downloads and keeps up to date copies of software and add-ons under development based on definitions stored in `mrs.developer.json`. @@ -697,7 +696,6 @@ Content Delivery Network CDN A Content Delivery Network (CDN) is a network of servers located in various geographic regions that work together to deliver web content to users quickly and efficiently. - unique identifier UID UID is an acronym meaning "unique identifier". From ad103a9717e96ad36d224cbd94a9fa321ac54376 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 2 Nov 2024 03:45:10 -0700 Subject: [PATCH 09/29] Revise Admin guide, adding commented link to new Volto add-ons index. --- docs/admin-guide/index.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/admin-guide/index.md b/docs/admin-guide/index.md index 8d8dd9907..6e89c4d82 100644 --- a/docs/admin-guide/index.md +++ b/docs/admin-guide/index.md @@ -3,13 +3,13 @@ myst: html_meta: "description": "How to install, operate, configure, and deploy Plone 6" "property=og:description": "How to install, operate, configure, and deploy Plone 6" - "property=og:title": "Admin Guide" + "property=og:title": "Admin guide" "keywords": "Plone 6, admin, install, configuration, deploy" --- (admin-index-label)= -# Admin Guide +# Admin guide In this part of the documentation, you can find how to install, operate, configure, and deploy Plone. @@ -31,6 +31,9 @@ install-pip run-plone configure-zope add-ons +% TODO: uncomment the following link when https://github.com/plone/volto/pull/6397 is merged. +% https://volto--6397.org.readthedocs.build/development/add-ons/install-an-add-on.html +% /volto/development/add-ons/index override-core /upgrade/index ``` From 8ee93391e56240e3b92837ccc027cb65b90b836a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 2 Nov 2024 03:51:57 -0700 Subject: [PATCH 10/29] Comments not supported in toctree, move after it --- docs/admin-guide/index.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/admin-guide/index.md b/docs/admin-guide/index.md index 6e89c4d82..9ac48e4ed 100644 --- a/docs/admin-guide/index.md +++ b/docs/admin-guide/index.md @@ -31,12 +31,13 @@ install-pip run-plone configure-zope add-ons -% TODO: uncomment the following link when https://github.com/plone/volto/pull/6397 is merged. -% https://volto--6397.org.readthedocs.build/development/add-ons/install-an-add-on.html -% /volto/development/add-ons/index override-core /upgrade/index ``` +% TODO: uncomment and add the following link to the Operate toctree when https://github.com/plone/volto/pull/6397 is merged. +% https://volto--6397.org.readthedocs.build/development/add-ons/install-an-add-on.html +% /volto/development/add-ons/index + ```{toctree} :maxdepth: 1 From dda4f2f7f2073414f3420b9a33be2b7635be614f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 2 Nov 2024 04:06:06 -0700 Subject: [PATCH 11/29] Split SUPPORTED_PYTHON_VERSIONS into two replacement variables for Plone 6.0 and 6.1. --- docs/_inc/_install-python.md | 2 +- docs/admin-guide/install-buildout.md | 4 ++-- docs/conf.py | 3 ++- docs/contributing/core/index.md | 4 ++-- docs/contributing/documentation/setup-build.md | 4 ++-- docs/install/create-project-cookieplone.md | 2 +- docs/install/create-project.md | 2 +- 7 files changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/_inc/_install-python.md b/docs/_inc/_install-python.md index 4f0add878..29bf96a84 100644 --- a/docs/_inc/_install-python.md +++ b/docs/_inc/_install-python.md @@ -1,6 +1,6 @@ Installing Python is beyond the scope of this documentation. However, it is recommended to use a Python version manager, {term}`pyenv`, that allows you to install multiple versions of Python on your development environment without destroying your system's Python. % TODO: uncomment this line after upgrading to plone-sphinx-theme and latest Sphinx which supports replacements inside includes. -% Plone requires Python version {SUPPORTED_PYTHON_VERSIONS}. +% Plone requires Python version {SUPPORTED_PYTHON_VERSIONS_PLONE60}. Plone requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12. diff --git a/docs/admin-guide/install-buildout.md b/docs/admin-guide/install-buildout.md index dbf8a2b3b..d5ef7ca5e 100644 --- a/docs/admin-guide/install-buildout.md +++ b/docs/admin-guide/install-buildout.md @@ -4,7 +4,7 @@ myst: "description": "Install Plone with Buildout" "property=og:description": "Install Plone with Buildout" "property=og:title": "Install Plone with Buildout" - "keywords": "Plone 6, install, Classic UI, buildout" + "keywords": "Plone 6, install, Classic UI, Buildout" --- (install-buildout-label)= @@ -24,7 +24,7 @@ For other installation options, see {ref}`get-started-install-label`. ## Prerequisites -- Python 3.10 or greater +- Python (SUPPORTED_PYTHON_VERSIONS_PLONE61) On Debian-based Linux systems you can install Python with the following command: diff --git a/docs/conf.py b/docs/conf.py index 43fd357ff..8644bb392 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -359,7 +359,8 @@ def source_replace(app, docname, source): "{PLONE_BACKEND_MINOR_VERSION}": "6.0", "{PLONE_BACKEND_PATCH_VERSION}": "6.0.13", "{NVM_VERSION}": "0.39.5", - "{SUPPORTED_PYTHON_VERSIONS}": "3.8, 3.9, 3.10, 3.11, or 3.12", + "{SUPPORTED_PYTHON_VERSIONS_PLONE60}": "3.8, 3.9, 3.10, 3.11, or 3.12", + "{SUPPORTED_PYTHON_VERSIONS_PLONE61}": "3.10, 3.11, or 3.12", } diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index a8fea1426..5ea3833ca 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -40,7 +40,7 @@ However, the following links and sections below may be helpful. ```{include} ../../volto/contributing/install-operating-system.md ``` -- Python {SUPPORTED_PYTHON_VERSIONS} +- Python {SUPPORTED_PYTHON_VERSIONS_PLONE60} - {term}`GNU make` - {term}`Git` - A C compiler @@ -50,7 +50,7 @@ However, the following links and sections below may be helpful. Installing Python is beyond the scope of this documentation. However, it is recommended to use a Python version manager, {term}`pyenv` that allows you to install multiple versions of Python on your development environment without destroying your system's Python. -Plone requires Python version {SUPPORTED_PYTHON_VERSIONS}. +Plone requires Python version {SUPPORTED_PYTHON_VERSIONS_PLONE60}. ### Make diff --git a/docs/contributing/documentation/setup-build.md b/docs/contributing/documentation/setup-build.md index db25b73fe..eb9452579 100644 --- a/docs/contributing/documentation/setup-build.md +++ b/docs/contributing/documentation/setup-build.md @@ -22,7 +22,7 @@ Installation of Plone 6 Documentation includes prerequisites and the repository ```{include} ../../volto/contributing/install-operating-system.md ``` -- {ref}`setup-build-installation-python-label` {SUPPORTED_PYTHON_VERSIONS} +- {ref}`setup-build-installation-python-label` {SUPPORTED_PYTHON_VERSIONS_PLONE60} - {ref}`setup-build-installation-gnu-make-label` - {ref}`setup-build-installation-graphviz-label` @@ -33,7 +33,7 @@ Installation of Plone 6 Documentation includes prerequisites and the repository Installing Python is beyond the scope of this documentation. However, it is recommended to use a Python version manager, {term}`pyenv` that allows you to install multiple versions of Python on your development environment without destroying your system's Python. -Plone requires Python version {SUPPORTED_PYTHON_VERSIONS}. +Plone requires Python version {SUPPORTED_PYTHON_VERSIONS_PLONE60}. (setup-build-installation-gnu-make-label)= diff --git a/docs/install/create-project-cookieplone.md b/docs/install/create-project-cookieplone.md index 3fed3af77..29237e3d0 100644 --- a/docs/install/create-project-cookieplone.md +++ b/docs/install/create-project-cookieplone.md @@ -43,7 +43,7 @@ Plone 6 has both hardware requirements and software prerequisites. ```{include} ../volto/contributing/install-operating-system.md ``` -- Python {SUPPORTED_PYTHON_VERSIONS} +- Python {SUPPORTED_PYTHON_VERSIONS_PLONE61} - {term}`pipx` - {term}`nvm` - {term}`Node.js` LTS 20.x diff --git a/docs/install/create-project.md b/docs/install/create-project.md index 2d8a46500..e4b30d081 100644 --- a/docs/install/create-project.md +++ b/docs/install/create-project.md @@ -45,7 +45,7 @@ Plone 6 has both hardware requirements and software prerequisites. ```{include} ../volto/contributing/install-operating-system.md ``` -- Python {SUPPORTED_PYTHON_VERSIONS} +- Python {SUPPORTED_PYTHON_VERSIONS_PLONE60} - {term}`pipx` - {term}`nvm` - {term}`Node.js` LTS 20.x From 6a1211b3c419feaf735e53a4ac093e4beb2da964 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 2 Nov 2024 04:32:47 -0700 Subject: [PATCH 12/29] Add include for installing Python. Add install Buildout as a pre-requisite. --- docs/_inc/_install-python-plone61.md | 8 ++++++++ docs/admin-guide/install-buildout.md | 17 ++++++++++++----- 2 files changed, 20 insertions(+), 5 deletions(-) create mode 100644 docs/_inc/_install-python-plone61.md diff --git a/docs/_inc/_install-python-plone61.md b/docs/_inc/_install-python-plone61.md new file mode 100644 index 000000000..ce7e2c497 --- /dev/null +++ b/docs/_inc/_install-python-plone61.md @@ -0,0 +1,8 @@ +Installing Python is beyond the scope of this documentation. +However, it is recommended to use a Python version manager, {term}`pyenv`, that allows you to install multiple versions of Python on your development environment without destroying your system's Python. +% TODO: uncomment this line after upgrading to plone-sphinx-theme and latest Sphinx which supports replacements inside includes. +% Plone requires Python version {SUPPORTED_PYTHON_VERSIONS_PLONE61}. + +Plone 6.0 requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12. + +Plone 6.1 requires Python version 3.10, 3.11, or 3.12. diff --git a/docs/admin-guide/install-buildout.md b/docs/admin-guide/install-buildout.md index d5ef7ca5e..f3685eb7e 100644 --- a/docs/admin-guide/install-buildout.md +++ b/docs/admin-guide/install-buildout.md @@ -22,16 +22,23 @@ For other installation options, see {ref}`get-started-install-label`. (install-buildout-prerequisites)= -## Prerequisites +## Prerequisites for installation -- Python (SUPPORTED_PYTHON_VERSIONS_PLONE61) +- For Plone 6.0, Python {SUPPORTED_PYTHON_VERSIONS_PLONE60} +- For Plone 6.1, Python {SUPPORTED_PYTHON_VERSIONS_PLONE61} +- Buildout -On Debian-based Linux systems you can install Python with the following command: -```shell -sudo apt install python3.12 python3.12-dev python3.12-venv +### Python + +```{include} /_inc/_install-python-plone61.md ``` +### Buildout + +See [Getting started with Buildout](http://www.buildout.org/en/latest/getting-started.html). + + ## Installation Select a directory of your choice: From ee90925be1024cc7e9ab966adfee32ef8f223a60 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 2 Nov 2024 05:05:30 -0700 Subject: [PATCH 13/29] Update include for installing Python, to avoid repetition. Update after walk-through of process, adding missing bits and pieces. --- docs/_inc/_install-python-plone61.md | 4 --- docs/admin-guide/install-buildout.md | 46 +++++++++++++++++++--------- 2 files changed, 31 insertions(+), 19 deletions(-) diff --git a/docs/_inc/_install-python-plone61.md b/docs/_inc/_install-python-plone61.md index ce7e2c497..71ced9e9c 100644 --- a/docs/_inc/_install-python-plone61.md +++ b/docs/_inc/_install-python-plone61.md @@ -2,7 +2,3 @@ Installing Python is beyond the scope of this documentation. However, it is recommended to use a Python version manager, {term}`pyenv`, that allows you to install multiple versions of Python on your development environment without destroying your system's Python. % TODO: uncomment this line after upgrading to plone-sphinx-theme and latest Sphinx which supports replacements inside includes. % Plone requires Python version {SUPPORTED_PYTHON_VERSIONS_PLONE61}. - -Plone 6.0 requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12. - -Plone 6.1 requires Python version 3.10, 3.11, or 3.12. diff --git a/docs/admin-guide/install-buildout.md b/docs/admin-guide/install-buildout.md index f3685eb7e..d6b56ee76 100644 --- a/docs/admin-guide/install-buildout.md +++ b/docs/admin-guide/install-buildout.md @@ -14,7 +14,7 @@ myst: This chapter describes how you can install Plone using {term}`Buildout`. This is one way to install Plone with the Classic UI. -Using Buildout will be the most familiar approach for admins who have experience with Plone 3, 4, or 5. +Using Buildout will be the most familiar approach for administrators who have experience with Plone 3, 4, or 5. ```{seealso} For other installation options, see {ref}`get-started-install-label`. @@ -26,7 +26,6 @@ For other installation options, see {ref}`get-started-install-label`. - For Plone 6.0, Python {SUPPORTED_PYTHON_VERSIONS_PLONE60} - For Plone 6.1, Python {SUPPORTED_PYTHON_VERSIONS_PLONE61} -- Buildout ### Python @@ -34,31 +33,33 @@ For other installation options, see {ref}`get-started-install-label`. ```{include} /_inc/_install-python-plone61.md ``` -### Buildout - -See [Getting started with Buildout](http://www.buildout.org/en/latest/getting-started.html). - ## Installation -Select a directory of your choice: +Select a directory of your choice. ```shell -mkdir -p /opt/plone && cd /opt/plone +mkdir -p /plone && cd /plone ``` -Create a Python virtual environment: +Create a Python virtual environment. ```shell python3 -m venv . ``` -Install the minimal Python packages needed in order to run Buildout: +Install the minimal Python packages needed in order to run Buildout. ```shell bin/pip install -r https://dist.plone.org/release/6-latest/requirements.txt ``` +Install Buildout into the Python virtual environment. + +```shell +bin/pip install zc.buildout +``` + Create a `buildout.cfg` file in your directory with the following contents: ```cfg @@ -77,12 +78,15 @@ eggs = Plone ``` -Run buildout: +Run Buildout. ```shell bin/buildout ``` +This may take a few minutes. + + ## Run Plone in foreground mode Start the instance for a quick test in foreground mode: @@ -91,21 +95,33 @@ Start the instance for a quick test in foreground mode: bin/instance fg ``` -Your instance starts in foreground mode, which is only advisable for troubleshooting or for local demonstration purposes. +Your instance starts in foreground mode. +This should be used only for troubleshooting or local demonstration purposes. + +Now you can visit `http://localhost:8080` in your browser. +Select {guilabel}`Create Classic UI Plone site`. + +Enter {guilabel}`username` of `admin`, and {guilabel}`password` of `admin`. + +Fill out the form as needed, and click {guilabel}`Create Plone Site`. + +You will be redirected to your new Plone instance. + +To stop the Plone instance in foreground mode, type {kbd}`CTRL-C`. -Now you can call the url `http://localhost:8080` in your browser and you can add a **Classic UI Plone site**. ## Start Plone as a background service -Start the instance: +Start the instance. ```shell bin/instance start ``` + ## Stop Plone as a background service -Stop the instance: +Stop the instance. ```shell bin/instance stop From a9163ca0d4a3c1482f72b4a0c35312d697576b20 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 2 Nov 2024 05:41:52 -0700 Subject: [PATCH 14/29] The buildout instructions install only Plone 6.0.x --- docs/admin-guide/install-buildout.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/admin-guide/install-buildout.md b/docs/admin-guide/install-buildout.md index d6b56ee76..826b6ec02 100644 --- a/docs/admin-guide/install-buildout.md +++ b/docs/admin-guide/install-buildout.md @@ -24,13 +24,14 @@ For other installation options, see {ref}`get-started-install-label`. ## Prerequisites for installation -- For Plone 6.0, Python {SUPPORTED_PYTHON_VERSIONS_PLONE60} -- For Plone 6.1, Python {SUPPORTED_PYTHON_VERSIONS_PLONE61} +- For Plone 6.0, Python {SUPPORTED_PYTHON_VERSIONS_PLONE60} +% TODO: These instructions install Plone 6.0.x. Uncomment next line and change the subsequent include when Plone 6.1 is released and "latest". +% - For Plone 6.1, Python {SUPPORTED_PYTHON_VERSIONS_PLONE61} ### Python -```{include} /_inc/_install-python-plone61.md +```{include} /_inc/_install-python-plone60.md ``` From f40a97390621167beb87979925814ff609f12000 Mon Sep 17 00:00:00 2001 From: David Glick Date: Sat, 2 Nov 2024 10:43:00 -0700 Subject: [PATCH 15/29] Remove redundant installation of buildout --- docs/admin-guide/install-buildout.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/admin-guide/install-buildout.md b/docs/admin-guide/install-buildout.md index 826b6ec02..2089e7096 100644 --- a/docs/admin-guide/install-buildout.md +++ b/docs/admin-guide/install-buildout.md @@ -55,12 +55,6 @@ Install the minimal Python packages needed in order to run Buildout. bin/pip install -r https://dist.plone.org/release/6-latest/requirements.txt ``` -Install Buildout into the Python virtual environment. - -```shell -bin/pip install zc.buildout -``` - Create a `buildout.cfg` file in your directory with the following contents: ```cfg From 0ce3e0679b35664f5008e5e79e2dbb1f801bc54e Mon Sep 17 00:00:00 2001 From: David Glick Date: Sat, 2 Nov 2024 10:51:51 -0700 Subject: [PATCH 16/29] Recommend Plone 6.1 Python versions for core development --- docs/contributing/core/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 5ea3833ca..b97749a44 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -40,7 +40,7 @@ However, the following links and sections below may be helpful. ```{include} ../../volto/contributing/install-operating-system.md ``` -- Python {SUPPORTED_PYTHON_VERSIONS_PLONE60} +- Python {SUPPORTED_PYTHON_VERSIONS_PLONE61} - {term}`GNU make` - {term}`Git` - A C compiler @@ -50,7 +50,7 @@ However, the following links and sections below may be helpful. Installing Python is beyond the scope of this documentation. However, it is recommended to use a Python version manager, {term}`pyenv` that allows you to install multiple versions of Python on your development environment without destroying your system's Python. -Plone requires Python version {SUPPORTED_PYTHON_VERSIONS_PLONE60}. +Plone requires Python version {SUPPORTED_PYTHON_VERSIONS_PLONE61}. ### Make From 242ba6f000a2dbe87cd38a781d402cedfbb23d57 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 3 Nov 2024 01:22:10 -0800 Subject: [PATCH 17/29] Make includes for Python version more consistent and explicit --- docs/_inc/{_install-python.md => _install-python-plone60.md} | 2 +- docs/_inc/_install-python-plone61.md | 2 ++ docs/install/create-project-cookieplone.md | 2 +- docs/install/create-project.md | 2 +- 4 files changed, 5 insertions(+), 3 deletions(-) rename docs/_inc/{_install-python.md => _install-python-plone60.md} (87%) diff --git a/docs/_inc/_install-python.md b/docs/_inc/_install-python-plone60.md similarity index 87% rename from docs/_inc/_install-python.md rename to docs/_inc/_install-python-plone60.md index 29bf96a84..4ecb3f935 100644 --- a/docs/_inc/_install-python.md +++ b/docs/_inc/_install-python-plone60.md @@ -3,4 +3,4 @@ However, it is recommended to use a Python version manager, {term}`pyenv`, that % TODO: uncomment this line after upgrading to plone-sphinx-theme and latest Sphinx which supports replacements inside includes. % Plone requires Python version {SUPPORTED_PYTHON_VERSIONS_PLONE60}. -Plone requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12. +Plone 6.0 requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12. diff --git a/docs/_inc/_install-python-plone61.md b/docs/_inc/_install-python-plone61.md index 71ced9e9c..9533139b3 100644 --- a/docs/_inc/_install-python-plone61.md +++ b/docs/_inc/_install-python-plone61.md @@ -2,3 +2,5 @@ Installing Python is beyond the scope of this documentation. However, it is recommended to use a Python version manager, {term}`pyenv`, that allows you to install multiple versions of Python on your development environment without destroying your system's Python. % TODO: uncomment this line after upgrading to plone-sphinx-theme and latest Sphinx which supports replacements inside includes. % Plone requires Python version {SUPPORTED_PYTHON_VERSIONS_PLONE61}. + +Plone 6.1 requires Python version 3.10, 3.11, or 3.12. diff --git a/docs/install/create-project-cookieplone.md b/docs/install/create-project-cookieplone.md index 29237e3d0..465bfbfdc 100644 --- a/docs/install/create-project-cookieplone.md +++ b/docs/install/create-project-cookieplone.md @@ -53,7 +53,7 @@ Plone 6 has both hardware requirements and software prerequisites. #### Python -```{include} /_inc/_install-python.md +```{include} /_inc/_install-python-plone61.md ``` diff --git a/docs/install/create-project.md b/docs/install/create-project.md index e4b30d081..473311032 100644 --- a/docs/install/create-project.md +++ b/docs/install/create-project.md @@ -60,7 +60,7 @@ Plone 6 has both hardware requirements and software prerequisites. #### Python -```{include} /_inc/_install-python.md +```{include} /_inc/_install-python-plone60.md ``` From cec89fe2ff6126bdb7ec8462f14e2ab3d8533eb9 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 3 Nov 2024 01:57:13 -0800 Subject: [PATCH 18/29] Use an include for creating a Classic UI instance in foreground mode --- docs/_inc/_create-classic-ui-instance.inc | 15 +++++++++ docs/admin-guide/install-buildout.md | 25 +++++--------- docs/admin-guide/install-pip.md | 40 +++++++++++++---------- docs/contributing/core/index.md | 15 ++------- 4 files changed, 48 insertions(+), 47 deletions(-) create mode 100644 docs/_inc/_create-classic-ui-instance.inc diff --git a/docs/_inc/_create-classic-ui-instance.inc b/docs/_inc/_create-classic-ui-instance.inc new file mode 100644 index 000000000..417e28cbb --- /dev/null +++ b/docs/_inc/_create-classic-ui-instance.inc @@ -0,0 +1,15 @@ + +Your instance starts in foreground mode. +This should be used only for troubleshooting or local demonstration purposes. + +Now you can visit `http://localhost:8080` in your browser. +Click the button {guilabel}`Create Classic UI Plone site`. + +Enter {guilabel}`username` of `admin`, and {guilabel}`password` of `admin`. + +Enter values in the form, and click the button {guilabel}`Create Plone Site`. + +You will be redirected to your new Classic UI Plone site. + +To stop the Plone instance in foreground mode, type {kbd}`CTRL-C`. + diff --git a/docs/admin-guide/install-buildout.md b/docs/admin-guide/install-buildout.md index 2089e7096..3e34244f9 100644 --- a/docs/admin-guide/install-buildout.md +++ b/docs/admin-guide/install-buildout.md @@ -37,10 +37,11 @@ For other installation options, see {ref}`get-started-install-label`. ## Installation -Select a directory of your choice. +Select a directory of your choice, and change it to your working directory. ```shell -mkdir -p /plone && cd /plone +mkdir -p /plone +cd /plone ``` Create a Python virtual environment. @@ -55,7 +56,7 @@ Install the minimal Python packages needed in order to run Buildout. bin/pip install -r https://dist.plone.org/release/6-latest/requirements.txt ``` -Create a `buildout.cfg` file in your directory with the following contents: +Create a {file}`buildout.cfg` file in your directory with the following contents. ```cfg [buildout] @@ -67,6 +68,7 @@ parts = [instance] recipe = plone.recipe.zope2instance +# user = username:password - Use a secure token in a production environment. user = admin:admin http-address = 8080 eggs = @@ -82,7 +84,7 @@ bin/buildout This may take a few minutes. -## Run Plone in foreground mode +## Start Plone in foreground mode Start the instance for a quick test in foreground mode: @@ -90,19 +92,8 @@ Start the instance for a quick test in foreground mode: bin/instance fg ``` -Your instance starts in foreground mode. -This should be used only for troubleshooting or local demonstration purposes. - -Now you can visit `http://localhost:8080` in your browser. -Select {guilabel}`Create Classic UI Plone site`. - -Enter {guilabel}`username` of `admin`, and {guilabel}`password` of `admin`. - -Fill out the form as needed, and click {guilabel}`Create Plone Site`. - -You will be redirected to your new Plone instance. - -To stop the Plone instance in foreground mode, type {kbd}`CTRL-C`. +```{include} /_inc/_create-classic-ui-instance.inc +``` ## Start Plone as a background service diff --git a/docs/admin-guide/install-pip.md b/docs/admin-guide/install-pip.md index 5dcb2ae4a..e6597a1d0 100644 --- a/docs/admin-guide/install-pip.md +++ b/docs/admin-guide/install-pip.md @@ -20,45 +20,51 @@ It provides a basic installation without many additional tools to help with deve For other installation options, see {ref}`get-started-install-label`. ``` -## Prerequisites +(install-pip-prerequisites)= -- Python 3.10 or greater +## Prerequisites for installation -On Debian-based systems you can install Python with following command: +- For Plone 6.0, Python {SUPPORTED_PYTHON_VERSIONS_PLONE60} +% TODO: These instructions install Plone 6.0.x. Uncomment next line and change the subsequent include when Plone 6.1 is released and "latest". +% - For Plone 6.1, Python {SUPPORTED_PYTHON_VERSIONS_PLONE61} -```shell -sudo apt install python3.12 python3.12-dev python3.12-venv + +### Python + +```{include} /_inc/_install-python-plone60.md ``` + ## Installation -Select a directory of your choice: +Select a directory of your choice, and change it to your working directory. ```shell -mkdir -p /opt/plone -cd /opt/plone +mkdir -p /plone +cd /plone ``` -Create a Python virtual environment: +Create a Python virtual environment. ```shell python3 -m venv . ``` -Install Plone and a helper package: +Install Plone and a helper package, {term}`pipx`. ```shell bin/pip install -c https://dist.plone.org/release/6.0-latest/constraints.txt Plone pipx ``` + ## Create a Zope instance -Create a file `instance.yaml` with the following contents: +Create a file {file}`instance.yaml` in your directory with the following contents. ```yaml -# please change the password to a secure token! default_context: initial_user_name: "admin" +# Use a secure token for the password in a production environment. initial_user_password: "admin" wsgi_listen: "localhost:8080" debug_mode: false @@ -69,20 +75,20 @@ default_context: } ``` -Now run the {term}`cookiecutter` tool to create configuration for a Zope instance: +Now run the {term}`cookiecutter` tool to create configuration for a Zope instance. ``` bin/pipx run cookiecutter -f --no-input --config-file instance.yaml gh:plone/cookiecutter-zope-instance ``` + ## Start Plone in foreground mode -Start the instance for a quick test: +Start the instance for a quick test. ```shell bin/runwsgi -v instance/etc/zope.ini ``` -Your instance starts in foreground mode, which is only advisable for troubleshooting or for local demonstration purposes. - -Now you can call the url `http://localhost:8080` in your browser and you can add a **Classic UI Plone site**. +```{include} /_inc/_create-classic-ui-instance.inc +``` diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index b97749a44..e5efe59f3 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -124,14 +124,8 @@ Once that's done, you can start an instance of Plone with the following command. ./bin/instance fg ``` -To visit your Plone instance, you can open the link http://0.0.0.0:8080 in a web browser. - -You will be presented with several options. -Click the button {guilabel}`Create Classic UI Plone site`. - -Enter values in the form, and click the button {guilabel}`Create Plone Site`. - -You will be redirected to your new Classic UI Plone site. +```{include} /_inc/_create-classic-ui-instance.inc +``` ```{warning} Ignore the warning about accessing the Plone backend through its Classic UI frontend. @@ -141,11 +135,6 @@ They will not work with buildout. To contribute to Volto, you will need to start over, and follow {doc}`../volto`. ``` -To login, the default credentials are the following. - -- username: `admin` -- password: `admin` - (contributing-core-work-with-git-label)= From 16285023d5bf0ef0ec297878257f9e43820bd49e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 3 Nov 2024 02:35:14 -0800 Subject: [PATCH 19/29] Update create-project.md, removing note about not documenting how to install Plone via buildout, and specifying Plone 6.0. --- docs/conf.py | 1 - docs/install/create-project.md | 24 +++++++++--------------- 2 files changed, 9 insertions(+), 16 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 8644bb392..d79793765 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -358,7 +358,6 @@ def source_replace(app, docname, source): source_replacements = { "{PLONE_BACKEND_MINOR_VERSION}": "6.0", "{PLONE_BACKEND_PATCH_VERSION}": "6.0.13", - "{NVM_VERSION}": "0.39.5", "{SUPPORTED_PYTHON_VERSIONS_PLONE60}": "3.8, 3.9, 3.10, 3.11, or 3.12", "{SUPPORTED_PYTHON_VERSIONS_PLONE61}": "3.10, 3.11, or 3.12", } diff --git a/docs/install/create-project.md b/docs/install/create-project.md index 473311032..57bf59213 100644 --- a/docs/install/create-project.md +++ b/docs/install/create-project.md @@ -10,16 +10,16 @@ myst: (create-a-project-label)= -# Install Plone with cookiecutter-plone-starter (deprecated) +# Install Plone with `cookiecutter-plone-starter` (deprecated) -This chapter describes how you can create a web application using the {term}`cookiecutter-plone-starter` template. - -```{deprecated} Plone 6.1 & Volto 18 -This way of installing Plone is now deprecated. -It was the recommended way to start a new Plone project with **Plone 6.0** and **Volto 17 or earlier**. +```{deprecated} Plone 6.1 and Volto 18 +This method to install Plone is now deprecated. +It was the recommended way to start a new Plone project with Plone 6.0 and Volto 17 or earlier. For other installation options, see {ref}`get-started-install-label`. ``` +This chapter describes how you can create a web application using the {term}`cookiecutter-plone-starter` template. + This template creates a web application using Plone with the Volto frontend, along with tools for development and deployment. @@ -27,7 +27,7 @@ This template creates a web application using Plone with the Volto frontend, alo ## System requirements -Plone 6 has both hardware requirements and software prerequisites. +Plone 6.0 has both hardware requirements and software prerequisites. (install-packages-hardware-requirements-label)= @@ -159,15 +159,9 @@ Now the instructions to install Yarn should work. (install-packages-install-label)= -## Install Plone 6 - -We install Plone 6 with {term}`pipx`, {term}`Cookiecutter`, {term}`mxdev`, {term}`make`, and other developer tools. +## Install Plone 6.0 -```{note} -We do not maintain documentation for installing Plone 6 or later with `buildout`. -For Plone 5, `buildout` was the preferred installation method. -You can read the [documentation of how to install Plone 5 with `buildout`](https://5.docs.plone.org/manage/installing/installation_minimal_buildout.html), and adapt it to your needs for Plone 6. -``` +We install Plone 6.0 with {term}`pipx`, {term}`Cookiecutter`, {term}`mxdev`, {term}`make`, and other developer tools. Create a new directory to hold your project, and make it your current directory. From b9e86b0f19fd14f1aa5537cf1867da92216c3f5e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 3 Nov 2024 02:38:33 -0800 Subject: [PATCH 20/29] Rename _create-classic-ui-instance.inc to .md --- ...e-classic-ui-instance.inc => _create-classic-ui-instance.md} | 0 docs/admin-guide/install-buildout.md | 2 +- docs/admin-guide/install-pip.md | 2 +- docs/contributing/core/index.md | 2 +- 4 files changed, 3 insertions(+), 3 deletions(-) rename docs/_inc/{_create-classic-ui-instance.inc => _create-classic-ui-instance.md} (100%) diff --git a/docs/_inc/_create-classic-ui-instance.inc b/docs/_inc/_create-classic-ui-instance.md similarity index 100% rename from docs/_inc/_create-classic-ui-instance.inc rename to docs/_inc/_create-classic-ui-instance.md diff --git a/docs/admin-guide/install-buildout.md b/docs/admin-guide/install-buildout.md index 3e34244f9..f0f87cc2e 100644 --- a/docs/admin-guide/install-buildout.md +++ b/docs/admin-guide/install-buildout.md @@ -92,7 +92,7 @@ Start the instance for a quick test in foreground mode: bin/instance fg ``` -```{include} /_inc/_create-classic-ui-instance.inc +```{include} /_inc/_create-classic-ui-instance.md ``` diff --git a/docs/admin-guide/install-pip.md b/docs/admin-guide/install-pip.md index e6597a1d0..62ede6906 100644 --- a/docs/admin-guide/install-pip.md +++ b/docs/admin-guide/install-pip.md @@ -90,5 +90,5 @@ Start the instance for a quick test. bin/runwsgi -v instance/etc/zope.ini ``` -```{include} /_inc/_create-classic-ui-instance.inc +```{include} /_inc/_create-classic-ui-instance.md ``` diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index e5efe59f3..565f405b0 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -124,7 +124,7 @@ Once that's done, you can start an instance of Plone with the following command. ./bin/instance fg ``` -```{include} /_inc/_create-classic-ui-instance.inc +```{include} /_inc/_create-classic-ui-instance.md ``` ```{warning} From bc07aa74b9be6a675bde31f2b1db7e66713622ed Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 3 Nov 2024 02:48:08 -0800 Subject: [PATCH 21/29] Tidy up run-plone.md, removing "with "s. Make casing of `ctrl-c` consistent. --- docs/_inc/_create-classic-ui-instance.md | 2 +- docs/admin-guide/run-plone.md | 31 ++++++++++++------------ 2 files changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/_inc/_create-classic-ui-instance.md b/docs/_inc/_create-classic-ui-instance.md index 417e28cbb..2c768d90e 100644 --- a/docs/_inc/_create-classic-ui-instance.md +++ b/docs/_inc/_create-classic-ui-instance.md @@ -11,5 +11,5 @@ Enter values in the form, and click the button {guilabel}`Create Plone Site`. You will be redirected to your new Classic UI Plone site. -To stop the Plone instance in foreground mode, type {kbd}`CTRL-C`. +To stop the Plone instance in foreground mode, type {kbd}`ctrl-c`. diff --git a/docs/admin-guide/run-plone.md b/docs/admin-guide/run-plone.md index 728daaee6..d90e363be 100644 --- a/docs/admin-guide/run-plone.md +++ b/docs/admin-guide/run-plone.md @@ -4,7 +4,7 @@ myst: "description": "Run Plone" "property=og:description": "Run Plone" "property=og:title": "Run Plone" - "keywords": "Plone 6, run, start, command" + "keywords": "Plone 6, run, start, command, Cookieplone, Buildout, pip, cookiecutter-plone-starter" --- (run-plone-label)= @@ -17,24 +17,25 @@ There are different commands to run Plone, depending on which method you used to ## Run Plone in foreground mode -Running Plone in foreground mode will show output in the terminal. This is recommended while developing a Plone site. +Running Plone in foreground mode will show output in the terminal. +This is recommended while developing a Plone site. -with Cookieplone: +Cookieplone: : ```shell make backend-start ``` -with Buildout: +Buildout: : ```shell bin/instance fg ``` -with pip: +pip: : ```shell bin/runwsgi instance/etc/zope.ini ``` -with `cookiecutter-plone-starter`: +`cookiecutter-plone-starter`: : ```shell make start-backend ``` @@ -44,14 +45,14 @@ For any of these commands, press {kbd}`ctrl-c` to stop the process. ## Run Volto -If you are using the Volto frontend, you need to run the frontend in a separate process. +If you use the Volto frontend, you need to run the frontend in a separate process and terminal session. -with Cookieplone: +Cookieplone: : ```shell make frontend-start ``` -with `cookiecutter-plone-starter`: +`cookiecutter-plone-starter`: : ```shell make start-frontend ``` @@ -61,14 +62,14 @@ For any of these commands, press {kbd}`ctrl-c` to stop the process. ## Start Plone as a background service -with Buildout: +Buildout: : ```shell bin/instance start ``` ## Stop Plone as a background service -with Buildout: +Buildout: : ```shell bin/instance stop ``` @@ -78,22 +79,22 @@ with Buildout: The debug console gives you a Python prompt with the Plone site's configuration loaded. Use this for troubleshooting. -with Cookieplone: +Cookieplone: : ```shell make -C backend console ``` -with Buildout: +Buildout: : ```shell bin/instance debug ``` -with pip: +pip: : ```shell bin/zconsole debug instance/etc/zope.ini ``` -with `cookiecutter-plone-starter`: +`cookiecutter-plone-starter`: : ```shell make -C backend debug ``` From 72bfeee9528c66581af7a90f225f99b6222e5af6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 3 Nov 2024 03:05:24 -0800 Subject: [PATCH 22/29] Tidy up configure-zope.md --- docs/admin-guide/configure-zope.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/admin-guide/configure-zope.md b/docs/admin-guide/configure-zope.md index 0f05786ca..e703cd211 100644 --- a/docs/admin-guide/configure-zope.md +++ b/docs/admin-guide/configure-zope.md @@ -4,7 +4,7 @@ myst: "description": "Configure Zope options" "property=og:description": "Configure Zope options" "property=og:title": "Configure Zope" - "keywords": "Plone 6, Zope, instance, app server, config, cookiecutter-zope-instance" + "keywords": "Plone 6, Zope, instance, app server, config, Cookieplone, Buildout, pip, cookiecutter-plone-starter, cookiecutter-zope-instance, plone.recipe.zope2instance" --- (configure-zope-label)= @@ -15,19 +15,21 @@ Plone runs in an application server called {term}`Zope`. You can configure your Zope instance's options, including the following. -* persistent storage: blobs, direct filestorage, relation database, ZEO, and so on -* ports -* threads -* cache -* logging -* debugging and profiling for development +- persistent storage: blobs, direct file storage, relational database, ZEO, and other storage mechanisms +- ports +- threads +- cache +- logging +- debugging and profiling for development -## with Cookieplone + +## Via Cookieplone If you installed Plone using Cookieplone, `cookiecutter-plone-starter`, or pip, then Zope is configured using {term}`cookiecutter-zope-instance`. For a complete list of features, usage, and options, read [`cookiecutter-zope-instance`'s README](https://github.com/plone/cookiecutter-zope-instance#readme). -## with Buildout + +## Via Buildout If you installed Plone using Buildout, then Zope is configured using `plone.recipe.zope2instance`. For a complete list of features, usage, and options, read [`plone.recipe.zope2instance`'s README](https://pypi.org/project/plone.recipe.zope2instance/). From 8facc740134c5e9c2b99157478e6037ec15563dc Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 3 Nov 2024 03:24:59 -0800 Subject: [PATCH 23/29] Shorten headings --- docs/admin-guide/configure-zope.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin-guide/configure-zope.md b/docs/admin-guide/configure-zope.md index e703cd211..04b009522 100644 --- a/docs/admin-guide/configure-zope.md +++ b/docs/admin-guide/configure-zope.md @@ -23,13 +23,13 @@ You can configure your Zope instance's options, including the following. - debugging and profiling for development -## Via Cookieplone +## Cookieplone If you installed Plone using Cookieplone, `cookiecutter-plone-starter`, or pip, then Zope is configured using {term}`cookiecutter-zope-instance`. For a complete list of features, usage, and options, read [`cookiecutter-zope-instance`'s README](https://github.com/plone/cookiecutter-zope-instance#readme). -## Via Buildout +## Buildout If you installed Plone using Buildout, then Zope is configured using `plone.recipe.zope2instance`. For a complete list of features, usage, and options, read [`plone.recipe.zope2instance`'s README](https://pypi.org/project/plone.recipe.zope2instance/). From 7f7ba8c51d0435f527b69f767933231f2b8e6524 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 3 Nov 2024 03:40:06 -0800 Subject: [PATCH 24/29] Tidy up add-ons.md --- docs/admin-guide/add-ons.md | 80 +++++++++++++++++++++++-------------- 1 file changed, 51 insertions(+), 29 deletions(-) diff --git a/docs/admin-guide/add-ons.md b/docs/admin-guide/add-ons.md index c6c8e6fb3..e8b631e61 100644 --- a/docs/admin-guide/add-ons.md +++ b/docs/admin-guide/add-ons.md @@ -1,29 +1,33 @@ --- myst: html_meta: - "description": "Install Plone Add-ons" - "property=og:description": "Install Plone Add-ons" - "property=og:title": "Install Plone Add-ons" - "keywords": "Plone 6, addon, add-on, package, plugin, extension, install" + "description": "Install Plone add-ons" + "property=og:description": "Install Plone add-ons" + "property=og:title": "Install Plone add-ons" + "keywords": "Plone 6, add-on, package, plugin, extension, install" --- -(install-plone-addons-label)= +(install-plone-add-ons-label)= -# Install Plone Add-ons +# Install Plone add-ons -This chapter explains how to install {term}`add-ons ` as Python packages to extend the functionality of the Plone backend or Classic UI. +This chapter explains how to install {term}`add-ons ` as Python packages to extend the functionality of the Plone backend or Classic UI. ```{note} -The Volto frontend has its own system of add-ons using Node.js packages. See {doc}`/volto/addons/index`. +The Volto frontend has its own system of add-ons using Node.js packages. +% TODO: update the following link after https://github.com/plone/volto/pull/6397 is merged to point to `/development/add-ons/index`. +See {doc}`/volto/addons/index`. ``` -## with Cookieplone -Use the following instructions if you installed Plone with Cookieplone or `cookiecutter-plone-starter`. +## Cookieplone + +Use the following instructions if you installed Plone with either Cookieplone or `cookiecutter-plone-starter`. + ### Install an add-on -Add a line with the name of your add-on in `backend/requirements.txt`. +Add a line with the name of your add-on in the file {file}`backend/requirements.txt`. This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/). ``` @@ -31,10 +35,10 @@ collective.easyform==4.2.1 ``` ```{tip} -Including the add-on version ensures that it won't accidentally get upgraded in the future. +Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future. ``` -Also add the add-on to `zcml_package_includes` in {file}`backend/instance.yaml` to make sure its configuration will be loaded: +Also add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` to make sure its configuration will be loaded. ```yaml default_context: @@ -43,19 +47,23 @@ default_context: Stop the backend with {kbd}`ctrl-c`. -To actually download and install the new add-on, run: +To actually download and install the new add-on, run the following command. ```shell make backend-build ``` ```{note} -If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead.` +If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead. ``` Now restart the backend. -In your web browser, and assuming you are currently logged in as `admin`, visit the URL http://localhost:8080/Plone/prefs_install_products_form. +```{seealso} +{doc}`run-plone` +``` + +In your web browser, and assuming you are currently logged in as an administrator, visit the URL http://localhost:8080/Plone/prefs_install_products_form. Then click the {guilabel}`Install` button next to your add-on to complete installation of the add-on. @@ -68,7 +76,7 @@ At the bottom of the page, you should see the heading {guilabel}`Add-on Configur An add-on can be installed from a source control system such as GitHub. -Add a line with the name of your add-on in `backend/requirements.txt`. +Add a line with the name of your add-on in the file {file}`backend/requirements.txt`. This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/). ``` @@ -76,17 +84,18 @@ collective.easyform ``` ```{note} -When installing an add-on from source, it's best to not pin a version, to make sure we use the version that's currently available in the source control system. +When installing an add-on from source, it's best not to pin a version. +This way you always get the version that's currently available in the source control system. ``` -Also add the add-on to `zcml_package_includes` in {file}`backend/instance.yaml` to make sure its configuration will be loaded: +Next add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` so that its configuration will load. ```yaml default_context: zcml_package_includes: project_title, collective.easyform ``` -Finally, add the package's source to {file}`mx.ini`: +Finally, add the package's source to the file {file}`mx.ini`. ```cfg [collective.easyform] @@ -102,19 +111,23 @@ See the [documentation of `mxdev` in its README.md](https://github.com/mxstack/m Stop the backend with {kbd}`ctrl-c`. -To actually download and install the new add-on, run: +To actually download and install the new add-on, run the following command. ```shell make backend-build ``` ```{note} -If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead.` +If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead. ``` Now restart the backend. -In your web browser, and assuming you are currently logged in as `admin`, visit the URL http://localhost:8080/Plone/prefs_install_products_form. +```{seealso} +{doc}`run-plone` +``` + +In your web browser, and assuming you are currently logged in as an administrator, visit the URL http://localhost:8080/Plone/prefs_install_products_form. An upgrade step might need to be performed in the Plone control panel. Follow the upgrade information, if present. Else click the {guilabel}`Install` button to complete installation of the add-on. @@ -126,7 +139,7 @@ Use the following instructions if you installed Plone with Buildout. ### Install an add-on -Update {file}`buildout.cfg`. +Update the file {file}`buildout.cfg`. This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/). ```cfg @@ -150,10 +163,10 @@ collective.easyform = 4.2.1 ``` ```{tip} -Including the add-on version ensures that it won't accidentally get upgraded in the future. +Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future. ``` -To actually download and install the new add-on, run: +To actually download and install the new add-on, run the following command. ```shell bin/buildout @@ -161,11 +174,16 @@ bin/buildout Then restart your instance. +```{seealso} +{doc}`run-plone` +``` + + ### Install an add-on from source -An add-on can be installed from a source control system such as GitHub. +You can install an add-on from a source control system such as GitHub. -Update {file}`buildout.cfg`. +Update the file {file}`buildout.cfg`. This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/). ```cfg @@ -191,7 +209,7 @@ eggs = collective.easyform = git https://github.com/collective/collective.easyform.git ``` -To actually download and install the new add-on, run: +To actually download and install the new add-on, run the following command. ```shell bin/buildout @@ -199,6 +217,10 @@ bin/buildout Then restart your instance. +```{seealso} +{doc}`run-plone` +``` + ```{seealso} This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension. ``` From d8900d0a22f46465bbfa8e21165b721ca7f55cad Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 3 Nov 2024 03:58:06 -0800 Subject: [PATCH 25/29] Tidy up override-core.md --- docs/admin-guide/override-core.md | 49 +++++++++++++++++++++---------- 1 file changed, 34 insertions(+), 15 deletions(-) diff --git a/docs/admin-guide/override-core.md b/docs/admin-guide/override-core.md index 38f80abd4..0723576be 100644 --- a/docs/admin-guide/override-core.md +++ b/docs/admin-guide/override-core.md @@ -4,24 +4,25 @@ myst: "description": "Override core Plone packages" "property=og:description": "Override core Plone packages" "property=og:title": "Override core Plone packages" - "keywords": "Plone 6, core, package, version, override" + "keywords": "Plone 6, core, package, version, override, Cookieplone, cookiecutter-plone-starter, Buildout" --- (override-core-plone-packages-label)= # Override core Plone packages -Plone includes a lot of Python packages. -Sometimes it is necessary to override one or more package versions in order to fix a bug. +Plone includes a few hundred Python packages. +Sometimes you will need to override one or more package versions to fix a bug. -## with Cookieplone +## Cookieplone Use the following instructions if you installed Plone with Cookieplone or `cookiecutter-plone-starter`. + ### Override a core Plone package -Add a version override to {file}`mx.ini`. +Add a version override to the file {file}`mx.ini`. This example uses `plone.api`. ``` @@ -37,24 +38,28 @@ For an explanation of why Plone uses `mxdev`, see {ref}`manage-backend-python-pa Stop the backend with {kbd}`ctrl-c`. -To actually download and install the new package version, run: +To actually download and install the new package version, run the following command. ```shell make backend-build ``` ```{note} -If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead.` +If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead. ``` Now restart the backend. +```{seealso} +{doc}`run-plone` +``` + ### Install a core Plone package from source -`mxdev` can also be used to install core Plone packages from a source control system such as GitHub. +You can also use `mxdev` to install core Plone packages from a source control system such as GitHub. -Add the Plone package you want to check out in {file}`mx.ini`. +Add the Plone package you want to check out in the file {file}`mx.ini`. This example uses `plone.restapi`. ```cfg @@ -66,7 +71,7 @@ extras = test Stop the backend with {kbd}`ctrl-c`. -To actually download and install the new package version, run: +To actually download and install the new package version, run the following command. ```shell make backend-build @@ -78,14 +83,18 @@ If you installed Plone using `cookiecutter-plone-starter`, run `make build-backe Now restart the backend. +```{seealso} +{doc}`run-plone` +``` + -## with Buildout +## Buildout Use the following instructions if you installed Plone with Buildout. ### Override a core Plone package -Update {file}`buildout.cfg`. +Update the file {file}`buildout.cfg`. This example uses `plone.api`. ```cfg @@ -111,7 +120,7 @@ plone.api = 2.0.0a3 The version pins specified in the `[versions]` section will take precedence over the pins inherited from `https://dist.plone.org/release/6-latest/versions.cfg`. ``` -To actually download and install the new package version, run: +To actually download and install the new package version, run the following command. ```shell bin/buildout @@ -119,12 +128,16 @@ bin/buildout Then restart your instance. +```{seealso} +{doc}`run-plone` +``` + ### Install a core Plone package from source A core Plone package can be installed from a source control system such as GitHub. -Update {file}`buildout.cfg`. +Update the file {file}`buildout.cfg`. This example uses `plone.restapi`. ```cfg @@ -156,12 +169,18 @@ plone.restapi = Setting an empty version ensures that the copy of `plone.restapi` from source control will be used, instead of the version pin inherited from https://dist.plone.org/release/6-latest/versions.cfg. ``` -To actually download and install the new add-on, run: +To actually download and install the new add-on, run the following command. ```shell bin/buildout ``` +Then restart your instance. + +```{seealso} +{doc}`run-plone` +``` + ```{seealso} This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension. ``` From e2f617cca90690cef22980b51a16cb105a5873ff Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 3 Nov 2024 04:06:34 -0800 Subject: [PATCH 26/29] Change passive to active voice --- docs/install/containers/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/containers/index.md b/docs/install/containers/index.md index 6c925d4a9..0d75813d8 100644 --- a/docs/install/containers/index.md +++ b/docs/install/containers/index.md @@ -14,7 +14,7 @@ myst: The Plone 6 images have all the system requirements, prerequisites, and Plone 6 already installed, except those requirements needed for running the container engine itself. Using containers is the easiest way to deploy Plone 6. -Containers may also be used when {doc}`creating a Plone project `. +You may also use containers when {doc}`creating a Plone project `. The Plone 6 container images are compliant with the [Open Container Initiative (OCI)](https://opencontainers.org/). They should work with any OCI-compliant container engine for developing, managing, and running Plone 6 images. From 0675809af3218b72cb43e1479b9834943734010b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 3 Nov 2024 04:24:09 -0800 Subject: [PATCH 27/29] Tidy up docs/install/index.md by reformatting Try a Plone demo section, improving parity between Volto and Classic UI as frontends in Plone 6, and adding mention of PloneConf. --- docs/install/index.md | 31 ++++++++++++++++++++----------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/docs/install/index.md b/docs/install/index.md index 84c4707db..890ae545e 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -4,7 +4,7 @@ myst: "description": "Get started with Plone 6" "property=og:description": "Get started with Plone 6" "property=og:title": "Get started" - "keywords": "Plone 6, install, overview" + "keywords": "Plone 6, install" --- (get-started-label)= @@ -24,30 +24,41 @@ This part of the documentation helps you find the best way to get started with P Choose a version to demo. -- [Plone 6 with Volto frontend](https://demo.plone.org/) -- [Plone 6 with Classic UI](https://classic.demo.plone.org/login?came_from=/en) +https://volto.demo.plone.org/ +: Plone 6 with Volto frontend + +https://demo.plone.org/ +: Plone 6 with Volto frontend and some add-ons, including Volto Light Theme, with content that demonstrates all the content types of Plone and blocks in Volto + +[https://classic.demo.plone.org/](https://classic.demo.plone.org/login?came_from=/en) +: Plone 6 with Classic UI frontend (get-started-install-label)= ## Install Plone -First, choose a Plone frontend. [TODO: add link to explanation of how to choose] -(If you are following a [Plone training](https://training.plone.org/), it should specify which option to choose.) +First, choose a Plone user interface, or frontend. + +```{TODO} +Add link to explanation of how to choose a frontend. +``` + +If you are following a [Plone training](https://training.plone.org/), it should specify which option to choose. {doc}`create-project-cookieplone` : This is the recommended way to install Plone for a new project with the Volto frontend. {doc}`/admin-guide/install-buildout` -: This is one way to install Plone with the Classic UI. +: This is one way to install Plone with the Classic UI frontend. Using Buildout will be the most familiar way for admins who have experience with Plone 3, 4, or 5. {doc}`/admin-guide/install-pip` -: This is one way to install Plone with the Classic UI. +: This is one way to install Plone with the Classic UI frontend. It provides a basic installation without many additional tools to help with development. {doc}`create-project` -: This was the recommended way to install Plone 6.0 for a new project with the Volto frontend. +: Installing Plone 6.0 with `cookiecutter-plone-starter` was the recommended way to install for a new project with the Volto frontend, but it is now deprecated in Plone 6.1. {doc}`Install Plone as a contributor ` : This option is for developers who want to contribute to Plone and its packages. @@ -60,6 +71,7 @@ First, choose a Plone frontend. [TODO: add link to explanation of how to choose] The {doc}`/conceptual-guides/index` explain concepts to help you understand Plone. The community has created a set of [Plone trainings](https://training.plone.org/) which are hosted separately from the documentation. +Plone trainings take place at every annual Plone Conference. (get-started-contribute-label)= @@ -67,6 +79,3 @@ The community has created a set of [Plone trainings](https://training.plone.org/ ## Contribute to Plone See the {doc}`Contributor Guide ` to learn how to participate in the Plone community and contribute to our open source software. - - -(install-index-getting-started-label)= From c4954cf23fbe9c9476648962d625bc9a08485f66 Mon Sep 17 00:00:00 2001 From: David Glick Date: Sun, 3 Nov 2024 14:23:37 -0800 Subject: [PATCH 28/29] Use include for Python section of docs setup --- docs/contributing/documentation/setup-build.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/contributing/documentation/setup-build.md b/docs/contributing/documentation/setup-build.md index eb9452579..d6d663426 100644 --- a/docs/contributing/documentation/setup-build.md +++ b/docs/contributing/documentation/setup-build.md @@ -31,10 +31,8 @@ Installation of Plone 6 Documentation includes prerequisites and the repository ### Python -Installing Python is beyond the scope of this documentation. -However, it is recommended to use a Python version manager, {term}`pyenv` that allows you to install multiple versions of Python on your development environment without destroying your system's Python. -Plone requires Python version {SUPPORTED_PYTHON_VERSIONS_PLONE60}. - +```{include} /_inc/_install-python-plone60.md +``` (setup-build-installation-gnu-make-label)= From 52e2cd948567e6b8d6ddf2cdeac6a53a18818d47 Mon Sep 17 00:00:00 2001 From: David Glick Date: Sun, 3 Nov 2024 14:27:00 -0800 Subject: [PATCH 29/29] Use a myst-parser comment for TODO in /install/index.md --- docs/install/index.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/install/index.md b/docs/install/index.md index 890ae545e..c82a8db06 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -39,10 +39,7 @@ https://demo.plone.org/ ## Install Plone First, choose a Plone user interface, or frontend. - -```{TODO} -Add link to explanation of how to choose a frontend. -``` +% TODO: once https://github.com/plone/documentation/pull/1749 is merged, link to it If you are following a [Plone training](https://training.plone.org/), it should specify which option to choose.