Manage add-ons and packages
Contents
Manage add-ons and packages#
This chapter assumes you have previously installed Plone from its packages. 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
See also
For a complete list of features, usage, and options, read cookiecutter-zope-instance
's README.rst
.
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.5/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.5/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
See also
See the documentation of mxdev
in its README.md for complete information.
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:
load_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:
load_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:
load_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 = master
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 inbackend/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 usingcookiecutter-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.