Incremental preparation
plonex supervisor start prepares the project before starting Supervisor. Plonex
uses an embedded doit task runner; projects do
not need a Makefile or dodo.py. The normal plonex CLI remains the entry point.
Preview the work without installing packages, rendering outputs, starting services, or downloading constraints:
plonex supervisor start --plan
plonex project describe preparation
plonex project describe preparation --format json
The report includes the same task graph, freshness decisions, prerequisites, and
potentially affected services. A plan does not create preparation state. An
uncached remote Git profile must first be resolved with project compile, or
replaced with a local checkout; planning never clones it.
What startup prepares
flowchart TD
D[Generate requirements and constraints] --> E[Ensure virtualenv dependencies]
E --> H[Configured Supervisor helper services]
E --> S[Supervisor configuration and directories]
H --> R[Runtime templates for managed Plonex instances]
E --> C[Scheduled job program]
R --> F[Validate generated outputs]
S --> F
C --> F
F --> START[Start Supervisor]
Each task checks its own inputs and outputs after its prerequisites finish.
Prerequisites shared by multiple tasks execute once. A prerequisite that needs
work does not automatically force all downstream work: unchanged outputs can leave
downstream tasks current. The plan labels uncertain downstream checks as
check after prerequisites.
Supervisor programs invoking plonex instance start, plonex instance debug, or
plonex db start have their runtime templates prepared too. Normal runtime names,
configuration files, and command-line overrides apply. Non-Plonex executables
remain Supervisor’s responsibility.
services[].run_for: supervisor templates participate in the graph. Their declared
order is preserved. Other helper services are explicit hooks without a reliable
freshness contract, so they run on every startup preparation; the plan identifies
them as always evaluated.
When work becomes stale
Change |
Preparation |
|---|---|
Add, edit, or remove a requirement/constraint fragment |
Regenerate dependency inputs and reconcile installation |
Change a nested |
Reconcile affected dependency inputs |
Change an effective dependency option or source selection |
Reconcile installation |
Edit ordinary Python code in an editable selected source |
Skip installation |
Change a selected source’s project metadata or extras |
Reinstall that source and reconcile dependencies |
Edit a regularly installed selected source |
Reinstall that source |
Change an instance port or a runtime template |
Render affected outputs; skip dependency installation |
Change a Jinja include |
Render affected outputs |
Remove or edit a generated output |
Recreate it from its declared template |
Change installed distribution metadata outside plonex |
Reconcile the virtualenv |
No relevant change |
Skip preparation |
A constraint limits a package version; it does not request installation of that
package. Automatic preparation uses installation, not synchronization. Removed
requirements can therefore leave unused packages installed. Use the explicit
plonex dependencies sync command to remove packages no longer required.
Dependency checks include local profiles, fragment membership, nested local inputs,
selected source paths and metadata, configured Python, and conventional build
settings such as UV_*, PIP_*, and compiler flags. Runtime-only settings do not
invalidate installation. Arbitrary application environment variables are not
assumed to influence package builds.
Configured jobs add the plonex project runtime and Huey with its
statistics extension to the target environment’s dependency inputs. Manual-only jobs also request the
runtime; their Supervisor worker consumes explicitly enqueued work.
The virtualenv check observes interpreter identity and installed distribution metadata. It is not a full integrity scan of every installed Python file. Configuring a different Python version stops startup and asks you to recreate the virtualenv explicitly; preparation does not replace it.
Source metadata discovery covers pyproject.toml, setup.cfg, setup.py, and conventional
requirements files. Projects whose build configuration reads additional arbitrary
files should use an explicit dependency installation when those files change.
Remote inputs and reproducibility
Remote constraints are validated and cached under the configured
var_folder/cache/constraints/. Startup uses these snapshots and downloads missing
ones, including nested constraints. A moving URL does not silently change the
project on every startup.
An explicit plonex dependencies install or plonex dependencies sync refreshes
remote constraints. A failed download or an HTML response stops preparation and
preserves the previous constraints output. Remote requirement URLs still follow
uv’s fetching behavior when installation runs; prefer immutable URLs and pinned
requirements for deployments.
Remote Git profiles have stable checkouts under var/cache/profiles/ in the
project. They are reused across configuration loads. project describe profiles
shows their paths. Update a cached checkout explicitly, for example with
git -C PATH pull --ff-only, or manage the profile as your own local checkout.
Startup never updates source repositories implicitly, including projects setting
sources_update_before_dependencies: true for interactive dependency commands.
Successful work, failures, and concurrent commands
Preparation records content fingerprints rather than relying on modification times. Generated files are replaced atomically, and identical content preserves its timestamp. Jinja includes are evaluated afresh, including when a file’s modification time was preserved.
Receipts live under the configured var_folder/preparation/, with private
permissions. They contain digests and paths rather than raw configuration values
or credentials. Only successful tasks receive current receipts. Failed tasks
block startup and are retried on the next invocation. Prior output ownership is
retained separately during failures so cleanup can be retried safely.
A project lock serializes preparation and explicit dependency-install contexts. Freshness is checked after acquiring the lock, so concurrent commands can reuse each other’s completed work. Configuration edits while a prepared graph is waiting or running require retrying the command.
When a template declaration is removed, preparation removes its previously tracked, unchanged output. Unmanaged files are preserved. If an obsolete generated file was edited manually, preparation stops and asks you to move or remove it. Put lasting changes in source templates.
Prepared files and running processes
supervisor start ensures prerequisites even if Supervisor is already running.
It reports affected services when preparation changed their dependencies or
configuration. It does not restart those services automatically. Use the explicit
Supervisor commands to apply the intended change:
plonex supervisor update
plonex supervisor restart
update applies changed Supervisor program declarations; restart restarts the
existing managed programs. Plone database upgrades remain explicit through
plonex db upgrade.
This first graph covers Supervisor startup. supervisor status and supervisor stop
perform no preparation. Other command families retain their existing behavior;
dependencies install and dependencies sync record successful installation so
startup can reuse it.