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 Create a project with Volto (stable release).

Manage add-ons and packages#

Plone uses mxdev to manage packages and constraints.

See also

For an explanation of why Plone uses mxdev, see Manage backend Python packages.

mxdev usage overview#

The default set of files for mxdev is shown below. They are located in the backend directory of your project.

requirements.txt

-c constraints.txt
-e src/project_title

zope.testrunner

# Add required add-ons
# collective.easyform

constraints.txt

-c https://dist.plone.org/release/6.0.13/constraints.txt

mx.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.

make build-backend

make build-backend invokes mxdev, which generates the files requirements-mxdev.txt and constraints-mxdev.txt. It then invokes pip to install packages with the new requirements file.

To reload the packages, stop your Plone site with ctrl-c, and start it with the following command.

make start-backend

See also

See the documentation of mxdev in its README.md for complete information.

Add an add-on#

Add a line with the name of your add-on in requirements.txt. This example uses collective.easyform.

collective.easyform

Add it to instance.yaml to let Zope know that this add-on should be loaded:

default_context:
    zcml_package_includes: project_title, collective.easyform

Stop the backend with ctrl-c. Then apply your changes and start the backend. You do not need to stop the frontend.

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 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 Site Setup control panel. At the bottom of the page, you should see the heading Add-on Configuration, and a control panel to configure the add-on that you just installed.

Pin the version of an add-on#

Pin the version in constraints.txt.

collective.easyform==3.1.0

Add the add-on to requirements.txt:

collective.easyform

Add it to instance.yaml to let Zope know that this add-on should be loaded:

default_context:
    zcml_package_includes: project_title, collective.easyform

Stop the backend with ctrl-c. Then apply your changes and start the backend.

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 Install button to complete installation of the add-on.

Check out an add-on#

Add the add-on in requirements.txt:

collective.easyform

In mx.ini, specify the information to check out the add-on:

[collective.easyform]
url=git@github.com:collective/collective.easyform.git
branch=dev-branch-name
extras=test

Add it to instance.yaml to let Zope know that this add-on should be loaded:

default_context:
    zcml_package_includes: project_title, collective.easyform

Stop the backend with ctrl-c. Then apply your changes and start the backend.

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 Install button to complete installation of the add-on.

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 mx.ini:

[settings]
# constraints of Plone packages
version-overrides =
    plone.api>=2.0.0a3

Apply your changes and restart backend:

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.

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 mx.ini.

[plone.restapi]
url = git@github.com:plone/plone.restapi.git
branch = main
extras = test

Stop the backend with ctrl-c. Then apply your changes and start the backend.

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.

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 ctrl-c. Then build and run the Plone backend.

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.

See also

For an explanation of the command make build-backend, see make build-backend details.

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

See also

For a complete list of features, usage, and options, read cookiecutter-zope-instance's README.rst.