Plonex profiles

Caution

The plonex profiles have been created with AI assistance.

This repository provides reusable profiles for composing your Plone projects using plonex.

Each profile is a directory containing an etc/plonex.yml file.

Profile	Purpose
base	Initializes shared settings, UTC timezone, Chameleon cache, and translation compilation.
zeo	Adds a Supervisor program named zeoserver.
instances-1	Adds one ZEO client, instance1, on loopback port 8081.
instances-2	Adds instance1 and instance2 on ports 8081–8082.
instances-4	Adds four clients on ports 8081–8084.
db-maintenance	Adds disabled manual pack and offline-backup jobs.
development	Enables Zope debug and development environment settings.
debugtoolbar	Selects an editable development checkout of plone.app.debugtoolbar.

Choose at most one instance profile; development can use a foreground instance instead. These profiles do not themselves select a Plone version or install application-specific packages; configure those in the project. The zeo profile and the instance-N profiles can be used independently, for example on separate hosts. Instance clients need an accessible ZEO server and the matching shared blob storage, with paths and permissions configured for your deployment.

Compose profiles

Fetch the profiles you need using the Raw URL for each etc/plonex.yml. For example, from your project root:

for profile in base zeo instances-2 db-maintenance; do
  mkdir -p "profiles/$profile/etc"
  curl --fail --location "https://raw.githubusercontent.com/collective/plonex-profiles/main/$profile/etc/plonex.yml" \
    --output "profiles/$profile/etc/plonex.yml"
done

Then configure etc/plonex.yml:

profiles:
  - profiles/base
  - profiles/zeo
  - profiles/instances-2
  - profiles/db-maintenance

plone_version: 6.2-latest

These URLs track main; use a commit SHA in place of main for reproducible fetches. Repeat the download to update the local files. Plonex resolves remote profile URLs as Git repositories, so raw file URLs cannot be listed directly under profiles.

The base profile must come first because the other profiles extend its values using +services, +cron_jobs, +sources, +aliases, and +environment_vars.

Do not include two instance-count profiles together: they define the same names and targets.

The project file has higher precedence than the profiles. An ordinary services:, cron_jobs:, sources:, aliases:, or environment_vars: in the project replaces the corresponding profile value.

So remove the starter services: block created by plonex project init or intentionally use +services: to add project entries.

Likewise use +cron_jobs:, +sources:, +aliases:, and +environment_vars: to add or override entries without replacing the profile mappings.

An entry in an additive job or sources mapping replaces the whole entry with the same name, so include all its fields when overriding it.

Paths in profiles may also be relative to the project root.

Each instance listens on port_base plus its instance number.

The default port_base is 8080, giving ports 8081–8084.

Set an integer port_base to move the group together; for example, port_base: 9000 gives instance1 port 9001. The optional instance_1_port through instance_4_port settings override the corresponding calculated ports individually.

Programs listen on 127.0.0.1; arrange a local reverse proxy or edit the profile to change the interface.

Supervisor program names, runtime names and generated configuration paths are distinct for each instance. Avoid port conflicts with other local services.

Inspect and prepare the resulting project:

plonex project describe services
plonex cron list
plonex supervisor start --plan
plonex supervisor start
plonex supervisor status

Preparation may install project dependencies and writes generated configuration.

If supervisor is already running, run plonex supervisor update to apply added or removed program declarations; restart affected running programs separately when required.

Development settings

Add development to the profile list after base to enable Zope debug mode, verbose security, Python security-policy implementation, and default Python deprecation warnings. It also enables Chameleon template reload and debug output via environment_vars. These settings are for isolated development environments; do not use this profile on a public or production instance. Profile instance programs still bind to loopback. Remove the profile and restart affected instances to return to your project's normal settings.

Fetch base, zeo, and development as shown above, then configure:

profiles:
  - profiles/base
  - profiles/zeo
  - profiles/development

default_actions:
  - supervisor start
  - instance debug

Run plonex with no arguments to start Supervisor and its ZEO server, then run the instance in the foreground in debug mode. You can also run plonex supervisor start and plonex instance debug separately. Stop the foreground instance with Ctrl-C and use plonex supervisor stop when finished. No instances-1 profile is needed for this workflow.

Plone environment variables

The base profile sets TZ: UTC, CHAMELEON_CACHE under the project's var/cache/chameleon, and zope_i18n_compile_mo_files: 'true'. It does not choose site languages. Override or extend these settings in your project:

+environment_vars:
  TZ: Europe/Rome
  PTS_LANGUAGES: "en it"
  zope_i18n_allowed_languages: "en it"

The development profile adds CHAMELEON_RELOAD and CHAMELEON_DEBUG.

For an existing project created with plonex project init, merge the starter environment_vars: into +environment_vars: if you want to retain both. Be deliberate with allowed languages, cache/debug settings, and credentials; the profiles do not set passwords or a fixed application URL. Inspect the result with plonex project describe environment and plonex project describe configuration --key environment_vars instance start. Restart instances to pick up environment changes.

Example: develop plone.app.debugtoolbar from a checkout

The demo debugtoolbar profile selects an editable checkout of plone.app.debugtoolbar from its master branch.

It is separate from development, so enabling debug mode does not automatically clone or install an add-on. Fetch base, zeo, development, and debugtoolbar as shown above, and include them in the project configuration:

profiles:
  - profiles/base
  - profiles/zeo
  - profiles/development
  - profiles/debugtoolbar

default_actions:
  - supervisor start
  - instance debug

The profile provides an alias that runs the package's Zope tests with plonex test_debugtoolbar; additional arguments are passed to the test command. The built-in test command cannot be replaced by a project alias.

Then run the following from the project root:

plonex sources clone
plonex sources list
plonex dependencies install
plonex project describe sources

The default checkout is src/plone.app.debugtoolbar; install: true selects it for installation in editable mode. Clone and install access the network and modify the project. Remove a duplicate requirement or selection for the same checkout. The branch can change; choose a compatible revision or pin a commit for a reproducible project. Override a sources entry with its complete mapping. The current 2.x add-on supports Plone 6.2 and later; verify your version and constraints against its upstream documentation.

Start the debug instance and install the add-on in the Plone site through its add-on control panel. Package installation alone does not activate it in an existing site. The toolbar exposes diagnostic information and, for sufficiently privileged users, an interactive interpreter: use it only in an isolated development site.

Database maintenance

db-maintenance defines both jobs as disabled, meaning schedules do not run automatically. The default schedule is UTC; set cron_timezone to an IANA time zone if you enable a schedule.

Review the commands, timeouts, schedules, storage locations and recovery procedure for your deployment. Both jobs use the same Plonex job lock to avoid overlapping with each other, but it does not coordinate external pack or backup processes.

• pack-db invokes plonex db pack --days 7 and requires a running ZEO server. Test it and set enabled: true only when the retention and schedule suit the project.
• backup-db invokes plonex db backup, which requires ZEO and other FileStorage writers to be stopped and blob writers coordinated. Do not enable its schedule while ZEO is running. Arrange an external maintenance window and execute the job only after stopping writers. The snapshot is local to var/backups; plan independent storage, retention and regular restore tests separately. This profile does not stop services, prune backups or provide off-host copies.

For example, after stopping all writers and coordinating blob storage:

plonex cron run backup-db
plonex cron history backup-db
plonex cron logs backup-db

Manual execution is available for disabled jobs. It prepares the job runtime if needed; inspect its output and only restart services after confirming the result. See Plonex's database recovery documentation for the exact snapshot limitations.

Run the profile tests

Install Plonex and its dependencies into a Python environment, then from the root of this checkout run:

python -m unittest discover -s tests -v

The tests resolve each supported topology through Plonex, check supervisor preparation and port overrides, and verify that the maintenance jobs remain manual by default. They use temporary projects and do not start services or modify a deployment.