Migrating from Buildout or mxdev
This guide helps you move an existing Plone project to Plonex. It covers projects
using buildout.cfg, mx.ini, or both. Plonex can inventory their local
configuration, but it does not convert Buildout recipes, resolve Buildout
interpolation, or run mxdev for you. Review the project’s behavior and test the
result on a copy before changing a running deployment.
1. Inventory the existing project
From an environment with Plonex installed, inspect the existing project even if
it does not yet have etc/plonex.yml:
plonex --target /path/to/old-project project inspect-legacy
plonex --target /path/to/old-project project inspect-legacy --format json
The inspector reads buildout.cfg and mx.ini in that directory. It reports
common settings, source declarations, and recipe names. It does not follow
Buildout extends, execute recipes, resolve interpolation, inspect included
files, or change the project. Review the included files and generated
configuration yourself, especially custom recipes and scripts.
Record the working Python and Plone versions, requirements and effective pins, source revisions and local changes, enabled add-ons and ZCML, environment variables, ports, database and blob locations, scheduled jobs, and process manager configuration. Save the current deployment and recovery procedure so you can return to it if needed.
2. Create a staging project
Use a separate directory and a compatible Python environment for the migration:
plonex project init /path/to/plonex-staging
cd /path/to/plonex-staging
init writes a starter etc/plonex.yml, creates a virtualenv, and installs its
starter dependencies. It uses a Plone 6.2 default: this is not a detection of
your existing project’s version. It may initialize and commit a Git repository
in a directory that does not already contain one. Inspect and adjust the
starter configuration, constraints, and dependencies before using it for your
application. Do not assume an older Plone application is compatible with that
default or with the selected Python version.
Keep staging’s database, blob storage, ports, and process manager separate from production. In particular, do not start a second ZEO server against a live FileStorage. If staging must connect to an existing ZEO server, agree on access and shared blob-storage semantics first; use a copy for upgrade experiments.
3. Move requirements and source checkouts
Choose one owner per checkout. Either continue using mxdev to generate the inputs and manage its sources, or declare those sources in Plonex. Mixing both owners for the same checkout can produce conflicting installs.
Keep mxdev temporarily
Run mxdev using your existing project procedure. Set Plonex to consume its actual generated files; the following names are examples, not mxdev defaults:
# etc/plonex.yml
plonex_base_constraint: constraints-mxdev.txt
pip_requirements:
- "-r requirements-mxdev.txt"
Keep the starter requirements your project needs as well. Set paths relative to the Plonex project or use appropriate absolute paths, and ensure files referenced from those generated inputs are accessible. Inspect the generated files for editable paths and nested includes before installing. Run mxdev again when its inputs change; Plonex does not generate these files or update mxdev’s checkouts. Remove duplicate Plonex source selections for those same packages. See dependency and constraint configuration.
Move source ownership to Plonex
Translate each selected repository, revision, extras, and install mode after
reviewing its original declaration. For example, a Buildout [sources] Git
entry or an mxdev section with a Git URL and branch might become:
# etc/plonex.yml
sources:
my.addon:
repo: https://github.com/example/my.addon.git
rev: main # Replace with the branch, tag, or commit you actually use.
install: true
extras: [test]
install: true selects the checkout for installation; selected sources are
editable by default. Use editable: false for a regular installation, and
path or subdirectory where the checkout layout requires them. Entries
without install: true are checkout-only. Plonex manages these checkouts through
Gitman, so review non-Git sources and custom checkout behavior separately.
Remove the corresponding old editable requirements and stop mxdev from
selecting the same packages. Move normal distribution requirements to
pip_requirements or etc/requirements.d/, and version pins to
etc/constraints.d/ or a suitable base constraints file. Buildout version
sections, constraints, and Python package metadata are not identical; check the
resulting resolver inputs rather than copying syntax mechanically.
plonex sources clone
plonex sources list
plonex dependencies install
plonex project describe sources
plonex project describe dependencies
The clone and install commands change the staging project and can access
repositories or package indexes. dependencies install does not remove unrelated
installed distributions; dependencies sync does, so use sync only after
reviewing the complete intended requirements.
4. Translate runtime and operations
Existing concern |
Where to review it in Plonex |
|---|---|
ZEO server and connection |
|
Zope/Plone instances |
|
Package requirements and versions |
|
|
|
Supervisor parts |
|
Cron jobs |
|
ZCML and custom Zope configuration |
|
Backup recipes |
The existing recovery procedure and Plonex backup and recovery |
Other recipes, scripts, and deployment hooks |
Review and migrate their behavior manually |
These are areas to compare, not one-to-one recipe conversions. Check effective configuration before starting processes:
plonex project describe configuration
plonex project describe configuration --key zeo_address db start
plonex project doctor
plonex supervisor start --plan
The --plan command previews preparation without starting Supervisor. The
configuration guide explains profiles, environment variables,
and generated templates; scheduled jobs describes the job runtime.
Review each scheduled task before enabling it in the new environment, so it does
not run twice during migration.
5. Test data and cut over
Make and verify a backup using the existing deployment’s procedure. Include the matching blob storage and any additional databases or external data.
Restore a consistent copy into isolated staging storage and confirm its paths, ownership, and permissions. Coordinate all writers when taking the copy. A
Data.fsfile alone does not contain blob data.Start the staging services with
plonex supervisor start; inspectplonex supervisor statusand the application logs. Test add-ons, login, ZCML, URLs, background jobs, integrations, and representative content.If the application requires upgrades, test them against the staging copy and check the results. Plonex’s
db upgradeusescollective.ftw.upgrade; install and enable it first. A successful environment install does not run application upgrade steps automatically.Plan the final cutover with a maintenance window: stop or otherwise coordinate all writers, take a fresh consistent backup, rehearse recovery, move the final data and blobs according to your storage setup, and start the intended services. Keep the old configuration and verified backup until the new deployment is accepted. Do not let old and new deployments write independently to divergent copies of the database.
Plonex backup and recovery documents its own offline snapshot format and limitations. Existing repozo backups are not automatically converted into that format; restore them with the original procedure and separately managed blob backups. After cutover, establish and test the new backup schedule.