Package: p3do
p3do - let 'em minions do itp3do (pronouncedpee-three-duh) is a collection of command-line utilities for
p3d. It allows you to conjure some tedious operations right from your magic little
fingertips.Installation•Getting started•Commands•ContributeInstallationp3dois built with Python 3.8 or later. You can get Python from your package
manager du jour or download and install it fromhttps://www.python.org/downloads/(looking at you Windows. Mac.
Whyihavetobother. Veryannoyingyouare.)p3dois published to theCheeseShopand
hence can be installed with pip:pipinstallp3doTo upgradep3doto the latest version, run:pipinstall--upgradep3dop3doinstalls itself as a command. If your$PATHis set up correctly you
will be able to just invokep3dolike sop3do--helpShell Completionp3dosupports shell completion (tab completion). Shell completion is supported
for bash, zsh and fish shells. For each of these, the autocompletion script is
different.Bash 4.4 and later:# add to your ~/.bashrceval"$(_P3DO_COMPLETE=bash_sourcep3do)"Zsh:# add to your ~/.zshrc:eval"$(_P3DO_COMPLETE=zsh_sourcep3do)"Fish:#  ~/.config/fish/completions/p3do.fisheval(env_P3DO_COMPLETE=fish_sourcep3do)Getting StartedLight a bonfire and whisperp3doin the most conspirative voice available to
you. Then start a terminal.p3dois hierarchical, self-documenting and discoverable. The best way to start
is to just typep3do. This will show you the available commands and some
description. From there you can drill down the hierarchy for useful sub-command.Each sub-command/command group has special flags and configuration. How to use
them is explained inCommandsfor each of them separately. You can
also usep3d <group> <command> --helpin your terminal for concise on-line
help.Commandsp3dois hierarchical. Commands are batched into groups which can be further
nested into parent groups. We follow the same principle in the documentation
here.jk: Jenkins commandsbuild: Run theP3D-BUILDjenkins job with smart branch
detectiondeploy: Run theP3D-Build-Deploy-PoolParty-(parent-pom)jenkins job with smart branch detectionpp: PoolParty commandsencrypt: Encrypt a clear text with poolparty encryptiondecrypt: Decrypt a secret text with poolparty encryptioninstall-snapshot: Download and run latest snapshot installer. Linux only.mock-server: Run a mock server for debugging external
services integration (Semantic Middleware Configurator).encrypt-license: Encrypt a PoolParty licensedecrypt-license: Decrypt a PoolParty licensekc: Keycloak commandsKC Configuration: Not a command but read this first!add-mappers: Add mappers to IdPs from realm exportgh: GitHub commandsdeploy-key: Add a deployment key to a GitHub repositorygs: GraphSearch commandscreate-documents: Push dummy documents into a ppgs searchspacejkCommands in this group allow to perform common operations on Jenkins.buildStart theP3D-BUILDjob from the command line with smart branch detection.
For this commandgithas to be installed.Per default (and outside a git repository) builds thedevelopbranch of
PoolParty.When inside a git repository p3do will automatically detect the current
branch and build it. This behavior can be disabled with--no-autodetect.The branch to build can be specified via--branch(note that this implies--no-autodetectinside a git repository).With--api-userand--api-keyyou can specify the credentials accessing the
Jenkins API. These credentials are cached and only need to be specified once. If
not specified and no cached credentials are found, p3do will ask for them
interactively. You can generate a token for--api-keyin yourJenkins Account
Settings.--api-useris the username you use to log in to Jenkins.# Build branch PoolParty develop without branch detectionp3dojkbuild--branchdevelopdeployStart theP3D-Build-Deploy-PoolParty-(parent-pom)job from the command line
with smart branch detection. For this commandgithas to be installed.Per default (and outside a git repository) deploys thedevelopbranch of
PoolParty.When inside a git repositoryp3dowill automatically detect the current branch
and deploy it. This behavior can be disabled with --no-autodetect.The branch to deploy can be specified via --branch (note that this implies
--no-autodetect inside a git repository).With--api-userand--api-keyyou can specify the credentials accessing the
Jenkins API. These credentials are cached and only need to be specified once. If
not specified and no cached credentials are found, p3do will ask for them
interactively. You can generate a token for--api-keyin yourJenkins Account
Settings.--api-useris the username you use to log in to Jenkins.TheSERVERargument is mandatory and must be a valid ssh server name.
PoolParty will be deployed to this server.# Deploy PoolParty develop branch to pp-lazer-kittens-dev without branch detectionp3dojkdeploy--branchdeveloppp-lazer-kittens-devppCommands in this group allow to perform operations useful for or related to
our dear PoolParty.encryptEncrypt a clear text with PoolParty encryption. The parameters for encryption
used by PoolParty can usually be found in thepoolparty.propertiesfile.This command can be used by specifying the encryption parameters directly as
options to p3do (--password,--salt,--strength) or with an interactive
prompt (just specify the clear text and leave out the options).To make sure that your command line processor does not mingle the input, always
wrap the clear text, password, and salt it in quotes if you are passing them as
options to p3do.For interactive prompt donotwrap them in quotes.Interactive prompt:# encrypt mysecret with# password H7dwBFDh3gEVDH1YecgikmOBpx9kKZ9nj1wJ5ZuhEeg=# salt Y+Fw/4dHBajqEGxOsEyfNSGsYYXE7JUyLmc3nRFrB84=# and 256 roundsp3doppencrypt"mysecret"Password:H7dwBFDh3gEVDH1YecgikmOBpx9kKZ9nj1wJ5ZuhEeg=# interactive promptSalt:Y+Fw/4dHBajqEGxOsEyfNSGsYYXE7JUyLmc3nRFrB84=# interactive promptStrength:256# interactive prompteYRLg0SUzGNSlfmS6MYrt8pnu5MTYU3EWVmNp1q/JFQ=With options:# encrypt mysecret with# password H7dwBFDh3gEVDH1YecgikmOBpx9kKZ9nj1wJ5ZuhEeg=# salt Y+Fw/4dHBajqEGxOsEyfNSGsYYXE7JUyLmc3nRFrB84=# and 256 roundsp3doppencrypt--password"H7dwBFDh3gEVDH1YecgikmOBpx9kKZ9nj1wJ5ZuhEeg="--salt"Y+Fw/4dHBajqEGxOsEyfNSGsYYXE7JUyLmc3nRFrB84="--strength256"mysecret"decryptDecrypt a secret text encrypted by PoolParty. The parameters for encryption/decryption used
by PoolParty can usually be found in thepoolparty.propertiesfile.This command can be used by specifying the encryption parameters directly as
options to p3do (--password,--salt,--strength) or with an interactive
prompt (just specify the clear text and leave out the options).To make sure that your command line processor does not mingle the input, always
wrap the clear text, password, and salt it in quotes if you are passing them as
options to p3do.For interactive prompt donotwrap them in quotes.Interactive prompt:# decrypt 6NjzLmQp7kGM7bbezhQX1G2hrqCoqLrC32ayBTjQVjU= with# password H7dwBFDh3gEVDH1YecgikmOBpx9kKZ9nj1wJ5ZuhEeg=# salt Y+Fw/4dHBajqEGxOsEyfNSGsYYXE7JUyLmc3nRFrB84=# and 256 roundsp3doppdecrypt"6NjzLmQp7kGM7bbezhQX1G2hrqCoqLrC32ayBTjQVjU="Password:H7dwBFDh3gEVDH1YecgikmOBpx9kKZ9nj1wJ5ZuhEeg=# interactive promptSalt:Y+Fw/4dHBajqEGxOsEyfNSGsYYXE7JUyLmc3nRFrB84=# interactive promptStrength:256# interactive prompteYRLg0SUzGNSlfmS6MYrt8pnu5MTYU3EWVmNp1q/JFQ=With options:# decrypt 6NjzLmQp7kGM7bbezhQX1G2hrqCoqLrC32ayBTjQVjU= with# password H7dwBFDh3gEVDH1YecgikmOBpx9kKZ9nj1wJ5ZuhEeg=# salt Y+Fw/4dHBajqEGxOsEyfNSGsYYXE7JUyLmc3nRFrB84=# and 256 roundsp3doppdecrypt--password"H7dwBFDh3gEVDH1YecgikmOBpx9kKZ9nj1wJ5ZuhEeg="--salt"Y+Fw/4dHBajqEGxOsEyfNSGsYYXE7JUyLmc3nRFrB84="--strength256"6NjzLmQp7kGM7bbezhQX1G2hrqCoqLrC32ayBTjQVjU="install-snapshotDownload and invoke the latest snapshot installer. Specify--pathto download
the installer to a specific folder. Otherwise, the installer will be installed
to a temporary directory.This command is restricted to Linux for now.p3doppinstall-snapshotmock-serverRuns a mock server for testing and debugging external integrationsPoolParty provides several integrations with external APIs/services (cf.
Semantic Middleware Configurator). This command starts a mock server for
debugging/testing such integrations.The port on which to run the server can be specified via --port. It defaults
to 5000.Webhook consumerStarts a server and echoes any request (+ auxiliary information) coming in.
In addition starts a healthcheck endpoint that just always returns200 OK.The webhook consumer url (to configure in Semantic Middleware Configurator)
ishttp://localhost:5000/hook.p3doppmock-serverencrypt-licenseEncrypts PoolParty license data with the PoolParty standard encryption and the
given encryption keyKEY must be the base64 encoded encryption key for PoolParty licenses
LICENSE path to the license data that shall be encrypted as PoolParty license filedecrypt-licenseDecrypts a PoolParty license with the PoolParty standard decryption and the given encryption keyKEY must be the base64 encoded encryption key for PoolParty licenses
LICENSE is the path to an encrypted license file usually ending in .keykcCommands in this group allow to perform operations for Keycloak. Most of them
need authentication and server information. Please readKC
Configurationfirst on how to add your configuration.Commands:KC Configuration: Not a command but read this first!add-mappers: Add mappers to IdPs from realm exportKC Configurationkc commands usually need some information about the server, realm and
authentication. This information can be read from a configuration file, given
via CLI parameters or interactively if information is missing. CLI parameters
take precendence and override any configuration read from a configuration file.Note:you don't need a configuration file at all. All (partial) parameters
can be specified via CLI arguments. Just leave out the--auth_configand--authflags.A full configuration file which specifies all available options looks like this:[test]server=https://keycloak.example.com/auth/username=adminuser_realm_name=masterpassword=passwordrealm_name=my-app[test]is the name of the configuration. You can have multiple configurations
for different servers in your config file.server,username,passwordare
rather self-explanatory.user_realm_nameis the realm theuseris in. This
is not necessarily the same realm as the one you want to modify.realm_nameis
the realm name you want to modify (it usually does not make sense to put this
into the config file).To specify the config file and config name you want to use, invoke ap3docommand like this:# `config.ini` is the config file, `test` is the config section you want to usep3dokcadd-mappers--auth_configconfig.ini--authtest<...otherarguments...>Note that you can override any configuration via CLI arguments:# Override `admin` from `config.ini` with `admin2`p3dokcadd-mappers--auth_configconfig.ini--authtest--usernameadmin2<...otherarguments...>The configuration can also be partial:[partial-test]server=https://keycloak.example.com/auth/username=adminuser_realm_name=masterNote that we don't specify apasswordorrealm_namehere. You can now invokep3dowith# Complete `partial-test` via argumentsp3dokcadd-mappers--auth_configconfig.ini--authpartial-test--passwordpassword--realm_namemy-other-app<...otherarguments...>You can also just invokep3doas before and will be asked interactively to fill out the missing pieces:# No `password` or `realm_name` from `config.ini` or cli argumentsp3dokcadd-mappers--auth_configconfig.ini--authpartial-test<...otherarguments...># `p3do` will ask you to complete them interactivelyPassword:password
Realm_name:my-other-appadd-mappersAdd IdP mappers from a realm export.jsonto a realm. The IdP must already
exist and correspond to the IdP name specified in the mapper config. Keycloak
does not import mapper configuration by itself (yet?).# `realm-export.json` is the path the the export filep3dokcadd-mappers--auth_configconfig.ini--authtestrealm-export.jsonghCommands in this group allow to perform operations on GitHubpoolparty-semantic-suiteorganization. Most operations need an access token.
This can be generated in GitHub user settingshttps://github.com/settings/tokens.Commands:deploy-key: Add a deployment key to a GitHub repositorydeploy-keyAdd a deployment key to a GitHub repository.gsCommands in this group allow to perform operations useful for or related to
GraphSearch.Commands:create-documents: Push dummy documents into a ppgs searchspacecreate-documentsCreate a certain number of documents into an existing ppgs searchspace.p3doprompts the user for required arguments.Interactive prompt:p3dogscreate-documents
Amount[5]:Url[http://localhost:8081]:Searchspaceid:57e726ed-f2b1-44af-977e-dd156e50c6c5
Username[superadmin]:Password:Contributep3dois licensed under MIT and published to PyPI (including source). Do not
add sensitive company data. Any sensitive data has to be read from external
configuration files.ContributorsAll contributions are welcome. This can be new commands, improvements to the
on-line help, documentation or spelling mistakes. Just open a PR with your
changes. If your changes are larger, you find a bug but don't know how to fix
it, or you are just unsure if your idea fits, open an issue on GitHub first.MaintainersThep3domain branch is protected and PRs have to be approved by bymaintainers(code owners in GitHub lingo). Tooling like this can
easily grow out of control. Maintainers ensure that this is not happening top3do. Here are some guidelines.Every command inp3domust have a well known and feasible (manual)
alternativep3domust not smear over too complicated process. If a process is too
complicated fix the process.p3domust not obfuscate processes. If knowledge about how things work isn't
spread enough, spread it.p3domust not gatekeep processes. It is not a mechanism for access
management.p3dobelieves in the competency of its usersRelease MaintainersReleases are pushed toPyPI. This requires
a token with Maintainer or Owner status on PyPI.Releases are automatically created and pushed by aGitHub
Actionwhen
a tagged release is created in GitHub.Repository and release maintainers is probably but not necessarily the same set
of people.