diff --git a/docs/_inc/_create-classic-ui-instance.md b/docs/_inc/_create-classic-ui-instance.md new file mode 100644 index 000000000..2c768d90e --- /dev/null +++ b/docs/_inc/_create-classic-ui-instance.md @@ -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/_inc/_install-python-plone60.md b/docs/_inc/_install-python-plone60.md new file mode 100644 index 000000000..4ecb3f935 --- /dev/null +++ b/docs/_inc/_install-python-plone60.md @@ -0,0 +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_PLONE60}. + +Plone 6.0 requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12. diff --git a/docs/_inc/_install-python.md b/docs/_inc/_install-python-plone61.md similarity index 76% rename from docs/_inc/_install-python.md rename to docs/_inc/_install-python-plone61.md index 4f0add878..9533139b3 100644 --- a/docs/_inc/_install-python.md +++ b/docs/_inc/_install-python-plone61.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_PLONE61}. -Plone 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/add-ons.md b/docs/admin-guide/add-ons.md new file mode 100644 index 000000000..e8b631e61 --- /dev/null +++ b/docs/admin-guide/add-ons.md @@ -0,0 +1,226 @@ +--- +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, add-on, package, plugin, extension, install" +--- + +(install-plone-add-ons-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. +% 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`. +``` + + +## 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 the file {file}`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, 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 the file {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 the following command. + +```shell +make backend-build +``` + +```{note} +If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead. +``` + +Now restart the backend. + +```{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. + +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 the file {file}`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 not to pin a version. +This way you always get the version that's currently available in the source control system. +``` + +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 the file {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 the following command. + +```shell +make backend-build +``` + +```{note} +If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead. +``` + +Now restart the backend. + +```{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. + + +## with Buildout + +Use the following instructions if you installed Plone with Buildout. + +### Install an add-on + +Update the file {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, 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 the following command. + +```shell +bin/buildout +``` + +Then restart your instance. + +```{seealso} +{doc}`run-plone` +``` + + +### Install an add-on from source + +You can install an add-on from a source control system such as GitHub. + +Update the file {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 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. +``` diff --git a/docs/admin-guide/configure-zope.md b/docs/admin-guide/configure-zope.md new file mode 100644 index 000000000..04b009522 --- /dev/null +++ b/docs/admin-guide/configure-zope.md @@ -0,0 +1,35 @@ +--- +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, Cookieplone, Buildout, pip, cookiecutter-plone-starter, cookiecutter-zope-instance, plone.recipe.zope2instance" +--- + +(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 file storage, relational database, ZEO, and other storage mechanisms +- ports +- threads +- cache +- logging +- debugging and profiling for development + + +## 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). + + +## 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 new file mode 100644 index 000000000..9ac48e4ed --- /dev/null +++ b/docs/admin-guide/index.md @@ -0,0 +1,47 @@ +--- +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/create-project-cookieplone +install-buildout +install-pip +/install/create-project +``` + +```{toctree} +:caption: Operate +:maxdepth: 1 + +run-plone +configure-zope +add-ons +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 +:caption: Deploy + +/install/containers/index +``` diff --git a/docs/admin-guide/install-buildout.md b/docs/admin-guide/install-buildout.md new file mode 100644 index 000000000..f0f87cc2e --- /dev/null +++ b/docs/admin-guide/install-buildout.md @@ -0,0 +1,114 @@ +--- +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 administrators who have experience with Plone 3, 4, or 5. + +```{seealso} +For other installation options, see {ref}`get-started-install-label`. +``` + +(install-buildout-prerequisites)= + +## Prerequisites for installation + +- 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-plone60.md +``` + + +## Installation + +Select a directory of your choice, and change it to your working directory. + +```shell +mkdir -p /plone +cd /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 {file}`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 = username:password - Use a secure token in a production environment. +user = admin:admin +http-address = 8080 +eggs = + Plone +``` + +Run Buildout. + +```shell +bin/buildout +``` + +This may take a few minutes. + + +## Start Plone in foreground mode + +Start the instance for a quick test in foreground mode: + +```shell +bin/instance fg +``` + +```{include} /_inc/_create-classic-ui-instance.md +``` + + +## 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/admin-guide/install-pip.md b/docs/admin-guide/install-pip.md new file mode 100644 index 000000000..62ede6906 --- /dev/null +++ b/docs/admin-guide/install-pip.md @@ -0,0 +1,94 @@ +--- +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`. +``` + +(install-pip-prerequisites)= + +## Prerequisites for installation + +- 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-plone60.md +``` + + +## Installation + +Select a directory of your choice, and change it to your working directory. + +```shell +mkdir -p /plone +cd /plone +``` + +Create a Python virtual environment. + +```shell +python3 -m venv . +``` + +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 {file}`instance.yaml` in your directory with the following contents. + +```yaml +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 + 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 +``` + +```{include} /_inc/_create-classic-ui-instance.md +``` diff --git a/docs/admin-guide/override-core.md b/docs/admin-guide/override-core.md new file mode 100644 index 000000000..0723576be --- /dev/null +++ b/docs/admin-guide/override-core.md @@ -0,0 +1,186 @@ +--- +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, Cookieplone, cookiecutter-plone-starter, Buildout" +--- + +(override-core-plone-packages-label)= + +# Override core Plone packages + +Plone includes a few hundred Python packages. +Sometimes you will need to override one or more package versions to fix a bug. + + +## 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 the file {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 the following command. + +```shell +make backend-build +``` + +```{note} +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 + +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 the file {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 the following command. + +```shell +make backend-build +``` + +```{note} +If you installed Plone using `cookiecutter-plone-starter`, run `make build-backend` instead.` +``` + +Now restart the backend. + +```{seealso} +{doc}`run-plone` +``` + + +## Buildout + +Use the following instructions if you installed Plone with Buildout. + +### Override a core Plone package + +Update the file {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 the following command. + +```shell +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 the file {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 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. +``` diff --git a/docs/admin-guide/run-plone.md b/docs/admin-guide/run-plone.md new file mode 100644 index 000000000..d90e363be --- /dev/null +++ b/docs/admin-guide/run-plone.md @@ -0,0 +1,102 @@ +--- +myst: + html_meta: + "description": "Run Plone" + "property=og:description": "Run Plone" + "property=og:title": "Run Plone" + "keywords": "Plone 6, run, start, command, Cookieplone, Buildout, pip, cookiecutter-plone-starter" +--- + +(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. + +Cookieplone: +: ```shell + make backend-start + ``` + +Buildout: +: ```shell + bin/instance fg + ``` + +pip: +: ```shell + bin/runwsgi instance/etc/zope.ini + ``` + +`cookiecutter-plone-starter`: +: ```shell + make start-backend + ``` + +For any of these commands, press {kbd}`ctrl-c` to stop the process. + + +## Run Volto + +If you use the Volto frontend, you need to run the frontend in a separate process and terminal session. + +Cookieplone: +: ```shell + make frontend-start + ``` + +`cookiecutter-plone-starter`: +: ```shell + make start-frontend + ``` + +For any of these commands, press {kbd}`ctrl-c` to stop the process. + + +## Start Plone as a background service + +Buildout: +: ```shell + bin/instance start + ``` + +## Stop Plone as a background service + +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. + +Cookieplone: +: ```shell + make -C backend console + ``` + +Buildout: +: ```shell + bin/instance debug + ``` + +pip: +: ```shell + bin/zconsole debug instance/etc/zope.ini + ``` + +`cookiecutter-plone-starter`: +: ```shell + make -C backend debug + ``` + +For any of these commands, press {kbd}`ctrl-d` to stop the process. 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..859852ac8 100644 --- a/docs/conceptual-guides/make-build-backend-walk-through.md +++ b/docs/conceptual-guides/make-build-backend-walk-through.md @@ -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 7e5dd4084..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` ``` @@ -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..d79793765 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -358,8 +358,8 @@ 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}": "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..565f405b0 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_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}. +Plone requires Python version {SUPPORTED_PYTHON_VERSIONS_PLONE61}. ### Make @@ -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.md +``` ```{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)= diff --git a/docs/contributing/documentation/setup-build.md b/docs/contributing/documentation/setup-build.md index db25b73fe..d6d663426 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` @@ -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}. - +```{include} /_inc/_install-python-plone60.md +``` (setup-build-installation-gnu-make-label)= 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 412e3eccb..8baf0d4d1 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 @@ -292,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`. @@ -693,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". diff --git a/docs/index.md b/docs/index.md index 40d53f511..9f4594162 100644 --- a/docs/index.md +++ b/docs/index.md @@ -32,8 +32,7 @@ Read the [documentation for the previous version, Plone 5](https://5.docs.plone. overview/index install/index -manage/index -upgrade/index +admin-guide/index deployment/index volto/index classic-ui/index diff --git a/docs/install/containers/index.md b/docs/install/containers/index.md index 5aef61ee6..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 <../create-project>` and {doc}`contributing to Plone `. +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. 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/create-project-cookieplone.md b/docs/install/create-project-cookieplone.md index 022199b04..465bfbfdc 100644 --- a/docs/install/create-project-cookieplone.md +++ b/docs/install/create-project-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. ``` @@ -40,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 @@ -50,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 7e7ab358f..57bf59213 100644 --- a/docs/install/create-project.md +++ b/docs/install/create-project.md @@ -1,29 +1,33 @@ --- 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. - -```{seealso} -For other installation options, see {doc}`/install/index`. +```{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. + (install-packages-system-requirements-label)= ## 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)= @@ -41,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 @@ -56,7 +60,7 @@ Plone 6 has both hardware requirements and software prerequisites. #### Python -```{include} /_inc/_install-python.md +```{include} /_inc/_install-python-plone60.md ``` @@ -155,15 +159,9 @@ Now the instructions to install Yarn should work. (install-packages-install-label)= -## Install Plone 6 +## Install Plone 6.0 -We install Plone 6 with {term}`pipx`, {term}`Cookiecutter`, {term}`mxdev`, {term}`make`, and other developer tools. - -```{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. diff --git a/docs/install/index.md b/docs/install/index.md index 1f8c95ce7..c82a8db06 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -1,59 +1,78 @@ --- myst: html_meta: - "description": "Install Plone 6" - "property=og:description": "Install Plone 6" - "property=og:title": "Install Plone 6" - "keywords": "Plone 6, install, overview" + "description": "Get started with Plone 6" + "property=og:description": "Get started with Plone 6" + "property=og:title": "Get started" + "keywords": "Plone 6, install" --- -(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 +``` -(install-index-getting-started-label)= -## Get started +(get-started-try-plone-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. +## Try a Plone demo -{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. +Choose a version to demo. + +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 -{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. +First, choose a Plone user interface, or 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. {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. +: 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 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 frontend. + It provides a basic installation without many additional tools to help with development. + +{doc}`create-project` +: 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}`Contribute to a Plone package ` +{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. +Plone trainings take place at every annual Plone Conference. -```{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. diff --git a/docs/manage/backend.md b/docs/manage/backend.md deleted file mode 100644 index 8f24599d2..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}`/install/create-project`. - - -## 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 -``` diff --git a/docs/upgrade/index.md b/docs/upgrade/index.md index b211116b6..be78a1e7f 100644 --- a/docs/upgrade/index.md +++ b/docs/upgrade/index.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: