Manage add-ons and packages#

This chapter assumes you have previously followed Create a project. In this section, we discuss details of the installation process so that you can customize your Plone installation. It also covers routine management tasks that a developer might perform.

Installation details with Cookiecutter#

Cookiecutter creates projects from project templates. The cookiecutter cookiecutter-plone-starter creates a Plone project that you can install using Make. It generates files for installing and configuring both the frontend and backend. For the backend, it uses cookiecutter-zope-instance to generate configuration files for a Zope WSGI instance.

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

Manage Plone backend packages with `mxdev`#

This section describes how to manage packages for the Plone backend with mxdev.

For developing add-ons for the Plone frontend, Volto, see Volto add-ons.

The problem with `pip`#

If you want to check out a Plone core package for development, or want to override the constraints of Plone, normally you would define constraints with a file constraints.txt to tell pip to install a different version of a Plone package.

# constraints.txt with unresolvable version conflict
-c https://dist.plone.org/release/6.0.11/constraints.txt
plone.api>=2.0.0a3

Unfortunately pip does not allow overriding constraints this way. mxdev solves this issue.

`mxdev` to the rescue!#

mxdev resolves Plone constraints according to your needs for version pinning or source checkouts. It reads its configuration file mx.ini, and your requirements.txt and constraints.txt files. Then it fetches the requirements and constraints of Plone. Finally, it writes new combined requirements in requirements-mxdev.txt and new constraints in constraints-mxdev.txt. Together these two files contain the combined requirements and constraints, but modified according to the configuration in mx.ini. The generated files indicate from where the constraints were fetched, and comments are added when a modification was necessary.

mxdev does not run pip or install packages. You must perform that step.

`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.11/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 Zope instance/Plone site with ctrl-c, and start it with the following command.

make start-backend

Common management tasks#

This section provides examples of common add-on and package management tasks. For the examples, we will modify the default files from the previous section mxdev usage overview. We will also use Classic UI for the interface because some packages and add-ons have not yet been updated to work with the new frontend.

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.

Backend installation details#

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.

bin/pip:
	@echo "$(GREEN)==> Setup Virtual Env$(RESET)"
	python3 -m venv .
	bin/pip install -U "pip" "wheel" "cookiecutter" "mxdev"

instance/etc/zope.ini:	bin/pip
	@echo "$(GREEN)==> Install Plone and create instance$(RESET)"
	bin/cookiecutter -f --no-input --config-file instance.yaml https://github.com/plone/cookiecutter-zope-instance
	mkdir -p var/{filestorage,blobstorage,cache,log}

# ...

.PHONY: build-dev
build-dev: instance/etc/zope.ini ## pip install Plone packages
	@echo "$(GREEN)==> Setup Build$(RESET)"
	bin/mxdev -c mx.ini
	bin/pip install -r requirements-mxdev.txt

The command make build-backend:

Invokes the target build-dev target in backend/Makefile.
This invokes the target instance/etc/zope.ini.
This invokes the target bin/pip.
- This creates a Python virtual environment if one does not exist.
- It installs and upgrades Python package management tools in that virtual environment.
Returning to the target instance/etc/zope.ini:
- This creates or updates the Zope configuration from its instance.yaml file using cookiecutter-zope-instance.
- Creates specified directories, if they do not exist.
Returning to the target build-dev:
- This generates the mxdev files as described above in mxdev usage overview.
- Installs Plone core packages and add-ons from the files generated by mxdev.

You can configure your Zope instance as described in the section Common management tasks.

Plone Documentation v6.0

Manage add-ons and packages

Contents

Manage add-ons and packages#

Installation details with Cookiecutter#

Configuration with `cookiecutter-zope-instance`#

Manage Plone backend packages with `mxdev`#

The problem with `pip`#

`mxdev` to the rescue!#

`mxdev` usage overview#

Common management tasks#

Add an add-on#

Pin the version of an add-on#

Check out an add-on#

Pin the version of a Plone package against constraints#

Check out a Plone package#

Build and start your instance#

Backend installation details#

Plone Documentation v6.0

Manage add-ons and packages

Contents

Manage add-ons and packages#

Installation details with Cookiecutter#

Configuration with cookiecutter-zope-instance#

Manage Plone backend packages with mxdev#

The problem with pip#

mxdev to the rescue!#

mxdev usage overview#

Common management tasks#

Add an add-on#

Pin the version of an add-on#

Check out an add-on#

Pin the version of a Plone package against constraints#

Check out a Plone package#

Build and start your instance#

Backend installation details#

Configuration with `cookiecutter-zope-instance`#

Manage Plone backend packages with `mxdev`#

The problem with `pip`#

`mxdev` to the rescue!#

`mxdev` usage overview#