Appendix: How can I…?
These recipes answer common questions. Run commands from your project directory, or provide --target /path/to/project before the command. Replace example names and paths with your own.
How do I start a new project?
plonex project init myproject
cd myproject
plonex supervisor start
plonex supervisor status
Supervisor starts the generated ZEO and WSGI programs in the background. For interactive development, the shell workflow below gives direct debugger input.
How do I run Plone with a debugger and still run commands?
plonex shell
plonex[myproject]> db start &
plonex[myproject]> instance debug
... press Ctrl-Z to return to the prompt ...
plonex[myproject]> options %2
plonex[myproject]> db upgrade
plonex[myproject]> fg %2
Ctrl-Z detaches without stopping the server. jobs lists the actual IDs;
logs %2 reads output and kill %2 stops that job. fg only reattaches jobs;
start new instances with instance debug. Exiting the shell stops its jobs.
Use an already-running ZEO server instead of starting a second one when your
project is configured with a shared database.
How do I develop an add-on from a checkout?
Declare its repository and editable installation together:
sources:
my.addon:
repo: git@github.com:example/my.addon.git
rev: main
install: true
extras: [test]
plonex sources clone
plonex dependencies install
plonex sources list
Editable installs use the checkout directly. A monorepo can add subdirectory;
path selects a custom checkout folder. Remove corresponding manual -e entries
when migrating. Distribution names such as my-addon are canonicalized, while
Python import names such as my.addon retain their dots.
Why do Python changes not appear in the application?
Check both the declaration and actual installation:
plonex project describe sources
plonex project describe dependencies
The source should have install: true, and its installed metadata should identify
the expected checkout as editable. A running process can still hold imported
Python modules; restart the instance after code changes when required. Dependency,
extra, or packaging changes need another dependencies install. An ordinary
editable: false installation contains built code rather than live source files.
How do I update dependencies and remove obsolete packages?
plonex sources update
plonex dependencies install
plonex dependencies sync
plonex dependencies outdated
install preserves unrelated installed packages. sync resolves the declared
requirements and removes packages outside that environment. To combine checkout
updates with installation, use dependencies install --update-sources.
Output reports actual changes; an unchanged run prints No package changes.
Where should additional requirements and pins go?
Use pip_requirements or etc/requirements.d/*.txt for requirements and
etc/constraints.d/*.txt for pins. These can also come from profiles.
When constraint fragments in the same directory pin the same package, the first
filename in alphabetical order takes precedence. Project constraints take
precedence over profile constraints.
dependencies add 'my-addon[test]' records a requirement and installs it.
Save missing pins with dependencies install --persist-local; the local pin file
stays separate from shared constraints. Use a raw text URL for
plonex_base_constraint, rather than a GitHub /blob/ HTML page.
Which file set this option, and why did it change?
plonex project describe configuration --key http_port
plonex project describe configuration --key http_port instance debug --port 8081
plonex project describe analytics instance debug
plonex project describe profiles
The configuration report shows the resolved value, winning definition, earlier
values, and Jinja references. Adding a command inspects that command’s defaults,
service-specific files, extra files, and CLI overrides. Analytics shows override
chains and configuration dependencies. Sensitive fields and derived secrets are
redacted. Use --format json for automation.
How do I open a useful project report?
plonex project describe --format html --browse
plonex project describe runtime --browse
plonex project describe jobs --browse
The complete report is var/plonex_description/index.html. It has responsive
layout, section navigation, search, file links, and definition history. Markdown
and JSON exports sit alongside it. Focused reports use their section name and
preserve the complete report. Existing file paths in the HTML report are clickable,
including configuration history. Open the report on the project host: browsers may
block local file links from a web server, and they decide whether to display or
download each file. Inspection does not install, compile, export the configured
environment, or start application services.
Why is my project not working as expected?
plonex project doctor
plonex project doctor --format json
plonex supervisor start --plan
The doctor reports configuration, virtualenv, source installation, constraint,
preparation, and local service problems with suggested next steps. It does not
install packages or change the project. Use --strict to make warnings fail a CI
check. See the doctor reference for its scope and
limitations.
How do I compare or recreate an environment?
plonex project snapshot create --output deployment.json
plonex project snapshot compare deployment.json
plonex project snapshot prepare deployment.json --to /path/to/new-venv
Snapshots capture installed versions, source revisions, and dependency inputs. Preparation verifies supported inputs before creating a separate environment. See project snapshots for limitations and reproducibility.
Can I inspect an existing mxdev or Buildout project?
Run plonex --target /path/to/project project inspect-legacy. The report reads
local configuration without running recipes or modifying the project. The
CLI reference shows how to consume mxdev’s
generated files while leaving mxdev in charge of generating them.
How do I run tests and stop in a failing test?
plonex dependencies add pytest
plonex test pytest my.addon -k login -x --pdb
plonex test zope my.addon -t Login
plonex test robot tests/robot/login.robot --browser firefox
Install the add-on’s testing extras and the runner it needs. Use Python import
names for package-based tests. Arguments after the package in test pytest
go to pytest, including -k, -x, and --pdb. The shell preserves terminal input
for interactive debugging.
How do I run a script or inspect the ZODB?
plonex instance run -- scripts/maintenance.py --argument value
plonex instance console
The console provides app. To establish a Plone site context:
from Testing.makerequest import makerequest
from zope.component.hooks import setSite
from zope.globalrequest import setRequest
app = makerequest(app)
setRequest(app.REQUEST)
site = app["Plone"]
setSite(site)
Use plone.api.env.adopt_user(username="your-user") for an explicit application
user context when needed. Commit intended database changes with
transaction.commit(); abort discarded changes with transaction.abort().
See Plone’s console documentation.
How do I run upgrade steps?
Run plonex db upgrade with the ZEO server running. Install and enable
collective.ftw.upgrade in the target project and site. Plonex starts a temporary
local instance with private authentication, runs the upgrade, and stops it. Output
is recorded in var/log/upgrade.logs.
To use an already running instance instead, pass
--url http://127.0.0.1:8081/ and configure its upgrade authentication. Review
and back up the database before planned deployment upgrades.
Why does Supervisor startup prepare dependencies and templates?
plonex supervisor start ensures that declared dependencies and generated runtime
files are current before starting Supervisor. It skips unchanged work. Requirement
and constraint changes trigger installation checks; changing an HTTP port only
regenerates affected runtime files.
plonex supervisor start --plan
plonex project describe preparation
The plan explains stale tasks and their prerequisites without executing them.
Preparation never implicitly updates Git sources, removes unused packages, runs
Plone upgrades, or restarts existing instances. Use dependencies sync for package
removal and explicit Supervisor commands to apply changes to running services.
See incremental preparation for caching, failures, and
remote profile behavior.
How do I apply Supervisor configuration changes?
plonex supervisor reread
plonex supervisor update
plonex supervisor status
update applies changed program declarations. restart restarts all managed
programs; graceful --interval 2 restarts them sequentially. Neither should be
confused with editing the currently running process’s configuration in memory.
options %JOB reports a shell job’s startup snapshot even after YAML changes.
How can I schedule work without a curl password or a CSRF exemption?
cron_timezone: Europe/Rome
cron_jobs:
StoreSessionStats:
schedule: "15 2 * * *"
callable: my.addon.jobs:store_session_stats
site: /Plone
context: sectors
user: scheduler
timeout: 900
lock: zope
lock_timeout: 300
enabled: false
Move the business logic into the callable, installed in the project virtualenv.
Create the named Plone user with the roles it needs; no password belongs in this
job declaration. Test with cron run StoreSessionStats, inspect cron logs and
cron history, then enable the schedule and apply Supervisor configuration.
Plonex installs the job runtime and Huey into the target virtualenv when jobs are configured. Supervisor launches the target interpreter directly. Manual-only job declarations still keep a worker for explicitly queued tasks.
A protected browser view can call the same function after POST and authenticator checks. The job runs through a dedicated ZEO client and owns its transaction; it does not invoke the browser view or disable CSRF. See the complete scheduled-job guide, including a protected view example.
How do I check scheduling times, failures, and overlap?
plonex cron list
plonex cron status
plonex cron queue
plonex cron history StoreSessionStats
plonex cron logs StoreSessionStats --tail 100
plonex project describe jobs --browse
Schedules use explicit IANA timezones, defaulting to UTC. Common lock names serialize related jobs; manual and daemon runs share those locks. Timeouts stop the job subprocess group and record the outcome. Retries default to zero; enable them only for work that tolerates repeating after a failure. The queue survives restarts, but missed periodic schedules are not replayed.
How do I inspect or retry queued work?
plonex cron status
plonex cron queue
plonex cron inspect TASK_ID
plonex cron retry TASK_ID
plonex cron revoke TASK_ID
plonex project describe queue
Monitoring uses Huey’s statistics extension in the target environment. Task IDs
link events to individual attempts and logs. retry creates a new task using the
current definition; revoke prevents a queued execution and does not kill a
running process. Add --format json for complete task IDs and structured output.
See the queue guide.
What changed in the command names?
There are no built-in synonyms such as both --sync and sync. Use
dependencies sync, dependencies outdated, instance debug, and
project describe. Update aliases, default command lists, deployment scripts,
and Supervisor command values from older projects. Configuration identities
such as run_for: fg and etc/plonex-runwsgi.yml retain their meaning.
The CLI migration table lists every removed form.
How can I back up before an upgrade?
Stop Supervisor and coordinate any other processes that write to the database or blob storage, then create a snapshot:
plonex supervisor stop
plonex db backup
The backup is offline and applies to the configured local FileStorage and blob storage. Follow backup and recovery for verification, limitations, and a restore into a separate directory before relying on the backup.
How can I recover without replacing the live database?
Choose a new destination and restore into it:
plonex db restore --to /path/to/new-recovery-directory
plonex db restore --from /path/to/snapshot --to /path/to/another-new-directory
Inspect and validate the recovered data using the procedure in Database backup and recovery before considering a cutover.
How can I run another instance on a different port?
With the project’s ZEO server already running, start another foreground instance and inspect its effective settings:
plonex options instance debug --port 8081
plonex instance debug --port 8081
Use plonex shell if you need to detach and reattach the process while running
other commands. See Interactive shell for job control and cleanup.
How can I identify what Supervisor will change before startup?
plonex supervisor start --plan
plonex project describe preparation --format json
The plan explains stale inputs and prerequisites. See Incremental preparation for remote profiles and the difference between preparing files and applying changes to running processes.
How can I investigate a failure systematically?
Symptom |
First action |
More detail |
|---|---|---|
Project cannot be found |
Check |
|
Unexpected setting |
|
|
Services are not running |
|
|
Setup is inconsistent |
|
|
Scheduled job failed |
|
|
Environment differs |
|