Hello world

This is me!

Autocomplete

Add something like this to your startup script:

eval "$(register-python-argcomplete plonex)"

Initialize your project

You can initialize a new project with the init command:

$ plonex init foo
INFO     Creating foo/tmp
INFO     Creating foo/etc
INFO     Creating foo/var
INFO     Creating foo/var/blobstorage
INFO     Creating foo/var/cache
INFO     Creating foo/var/filestorage
INFO     Creating foo/var/log
INFO     Creating foo/etc/plonex.yml
INFO     Project initialized

Describe your project

You can describe your project with the describe command:

plonex describe

By default this will create a markdown file in var/plonex_description/index.md and render it on the console. For the moment this displays only basic information about your project, but in the future it will be extended to include more useful information.

Install your packages

plonex dependencies

Start your project

After initializing your project, you can find an etc/supervisor directory with a couple of example files:

$ ls etc/supervisor
zeoclient.conf.example
zeoserver.conf.example

You can use them to decide which services are managed by supervisor.

For example to start the zeoserver service when supervisor starts, you can just copy the example file:

cp etc/supervisor/zeoserver.conf.example etc/supervisor/zeoserver.conf

If you want you can modify the file to suit your needs.

All the files with the extension .conf in the etc/supervisor directory will be loaded by supervisor.

Once you are ready, you can start supervisor with:

plonex supervisor start

Add an admin user

You can add an admin user with the adduser command, e.g.:

$ plonex adduser admin $ADMIN_PASSWORD
[ale@flo bar]$ plonex adduser admin admin
User admin created.

Add a package

If you want to add a package to your project, you can use the install command:

$ plonex install collective.pdbpp
...

Custom PyPI repository

If you want to use a custom PyPI repository, you can add in you pyproject.toml file the following snippet:

[tool.uv]
# Add command line parameters to the `pip` command, e.g.:
# index-strategy = "unsafe-best-match"

[[tool.uv.index]]
# You need to have this env variables set if you need to be authenticated:
# export UV_INDEX_PRIVATE_USERNAME=username
# export UV_INDEX_PRIVATE_PASSWORD=password
name = "private"
url = "https://pypi.acme.org/simple"


[[tool.uv.index]]
name = "pypi"
url = "https://pypi.org/simple"

--extra-index-url=https://pypi.acme.org/simple

Setting options/variables

You can set options in multiple ways.

1. In the command line (max priority)
2. In config files
3. In a etc/plonex-$servicename.*.yml
4. In a etc/plonex-$servicename.yml
5. In some etc/plonex.*.yml file (if any of them exists, precedence is given by alphabetical order)
6. In the etc/plonex.yml file
7. In the class definition options_default (lowest priority)

Log level

You can set the log level by setting the log_level variable, e.g.:

log_level: INFO

Valid values are: DEBUG, INFO, WARNING, ERROR, CRITICAL.

This value is ignored if you pass the -v/--verbose or the -q/--quiet option in the command line.

Zope instance configuration

You can customize the Zope instance configuration by setting some options.

Zope instance port

You can set the Zope default zope instance port by setting the http_port variable.

http_port: 8080

Zope instances environment variables

You can set environment variables for the Zope instances by setting the environment_vars variable.

Note in this example how you can reuse existing variables

environment_vars:
  PTS_LANGUAGES: it
  TZ: Europe/Rome
  zope_i18n_allowed_languages: '{{ environment_vars["PTS_LANGUAGES"] }}'
  zope_i18n_compile_mo_files: true
  CHAMELEON_CACHE: "{{ var_folder }}/cache/chameleon"
  CHAMELEON_RELOAD: true
  CHAMELEON_DEBUG: true

Also note the usage of the undocument (FIXME!!) var_folder variable.

Zope instance additional zcml

If you want to load additional zcml files, you can set the zcml_additional variable.

zcml_additional:
  - etc/extra.zcml
  - etc/extra-overrides.zcml

If the file ends in -overrides.zcml, it will be loaded after the default zcml files and override the existing configuration.

Your extra zcml files will be treated as jinja2 templates, so you can use any variable known to the instance to render them.

Run a script

You can run a script in the context of a zeo client with the run command:

plonex zeoclient run path/to/script.py [args ...]

Maintenance

With plonex you can easily maintain your DB.

Pack

To pack your ZODB database, you can use the pack command:

plonex zeoserver pack [--days DAYS]

Backup

To backup your ZODB database, you can use the backup command:

plonex zeoserver backup

TODO: backup blob with rsync.

Restore

TODO: implement the restore command.

Run tests

You can run tests with the test command:

plonex zopetest [-t TEST] package

For example to run all the tests in the plone.api package that match the name test_get, run:

$ plonex -q zopetest -t test_get plone.api
Running plone.api.tests.base.PloneApiLayer:Integration tests:
  Set up plone.testing.zca.LayerCleanup in 0.000 seconds.
  Set up plone.testing.zope.Startup in 0.040 seconds.
  Set up plone.app.testing.layers.PloneFixture in 1.146 seconds.
  Set up plone.api.tests.base.PloneApiLayer in 0.528 seconds.
  Set up plone.api.tests.base.PloneApiLayer:Integration in 0.000 seconds.
  Running:

  Ran 80 tests with 0 failures, 0 errors, 0 skipped in 2.326 seconds.
Tearing down left over layers:
  Tear down plone.api.tests.base.PloneApiLayer:Integration in 0.000 seconds.
  Tear down plone.api.tests.base.PloneApiLayer in 0.001 seconds.
  Tear down plone.app.testing.layers.PloneFixture in 0.007 seconds.
  Tear down plone.testing.zope.Startup in 0.001 seconds.
  Tear down plone.testing.zca.LayerCleanup in 0.000 seconds.

Robot tests helpers

Robot server

You can run a robot server with the robotserver command:

plonex robotserver

This will start a robot server connected to the Zope instance. You can browse the test server here on http://127.0.0.2:55001/plone.

By the default the robot server will use the layer: Products.CMFPlone.testing.PRODUCTS_CMFPLONE_ROBOT_TESTING.

You can change the layer by passing the -l/--layer option:

plonex robotserver --layer=My.Project.testing.MY_ROBOT_TESTING

Robot tests

You can run robot tests with the robottest command:

plonex robottest path/to/tests/*.robot

By default:

• this will run robot tests against the Zope instance running on http://127.0.0.2:55001/plone to match the robotserver configuration.
• it will use the browser firefox
• it will run all the tests found in the specified paths.

You can change the defaults by passing options. Refer to the help message for more information:

$ plonex robottest --help
Usage: plonex [options] robottest [-h] [-b BROWSER] [-t TEST] paths [paths ...]

Positional Arguments:
  paths                 Paths to the Robot Test files

Options:
  -h, --help            show this help message and exit
  -b, --browser BROWSER Browser to use for the tests (default: firefox)
  -t, --test TEST       Name of the test(s) to run. It supports regular expressions.