mirror of
https://github.com/NetherlandsForensicInstitute/hansken-extraction-plugin-sdk-documentation.git
synced 2026-05-09 03:37:07 +00:00
137 lines
5.9 KiB
Plaintext
137 lines
5.9 KiB
Plaintext
# Packaging
|
|
|
|
Extraction plugins are packaged as OCI images (also known as Docker images).
|
|
The OCI images are _labeled_ with the PluginInfo.
|
|
To automate packaging of a Python plugin and labeling the OCI image,
|
|
the Extraction Plugin SDK comes with three utility applications: `label_plugin`, `build_plugin` and `build_plugin_ci`.
|
|
|
|
To package a plugin, make sure that the Extraction Plugins SDK is [installed](getting_started.md#Installation), as well as Docker.
|
|
Next build and label your plugin as described in the following sections.
|
|
|
|
To verify that the image has been built, use the following command to view all local images:
|
|
|
|
```bash
|
|
docker images
|
|
```
|
|
|
|
Once your plugin is packaged and labelled, it can be published or 'uploaded' to Hansken.
|
|
See ":ref:`upload_plugin`" for instructions.
|
|
|
|
## `label_plugin`
|
|
|
|
`label_plugin` is a utility to add labels to an extraction plugin image.
|
|
To label a plugin, first build the plugin image with [docker build](https://docs.docker.com/reference/cli/docker/image/build/);
|
|
for example by using one of the following commands:
|
|
|
|
```shell
|
|
docker build . -t my_plugin
|
|
docker build . -t my_plugin --build-arg https_proxy=http://your_proxy:8080
|
|
```
|
|
|
|
Next, run the `label_plugin` utility to label the build plugin container:
|
|
|
|
```shell
|
|
label_plugin my_plugin
|
|
```
|
|
|
|
This utility will briefly start your plugin using Docker, and requests the PluginInfo from the plugin.
|
|
The information from the PluginInfo will be added as [labels](https://docs.docker.com/config/labels-custom-metadata/) to the plugin image.
|
|
The result of `label_plugin` is a plugin image that can be published to a docker/OCI image registry.
|
|
|
|
## `build_plugin`
|
|
|
|
The `build_plugin` extends `label_plugin` by also taking care of the docker build command.
|
|
Use this as an one-liner to both build and label your plugin image.
|
|
|
|
To build your plugin container image you can use the following command:
|
|
|
|
```bash
|
|
build_plugin DOCKER_FILE_DIRECTORY [DOCKER_IMAGE_NAME] [DOCKER_ARGS]
|
|
```
|
|
|
|
For example:
|
|
|
|
```bash
|
|
build_plugin .
|
|
```
|
|
|
|
and to pass proxy configurations to Docker:
|
|
|
|
```bash
|
|
build_plugin . --build-arg http_proxy="$http_proxy" --build-arg https_proxy="$https_proxy"
|
|
```
|
|
|
|
This will generate a plugin image:
|
|
* The extraction plugin is added to your local image registry (`docker images`),
|
|
* Note that the variables `$http_proxy` and `$https_proxy` are put in quotes, this is needed in case they contain
|
|
spaces,
|
|
* The image is tagged with two tags: `latest`, and your plugin version.
|
|
|
|
Arguments:
|
|
* `DOCKER_FILE_DIRECTORY`: Path to the directory containing the Dockerfile of the plugin.
|
|
* (Optional) `DOCKER\_IMAGE\_NAME`: Name of the docker image without tag. Note that docker image names cannot start with
|
|
a period or dash. If it starts with a dash, it will be interpreted as an additional docker argument (see
|
|
DOCKER\_ARGS). If no name is given the name defaults to `extraction-plugin/PLUGINID`, e.g.
|
|
`extraction-plugin/nfi.nl/extract/chat/whatsapp`.
|
|
* (Optional) `DOCKER\_ARGS`: Additional arguments for the docker command, which can be as many arguments as you like.
|
|
|
|
## `build_plugin_ci`
|
|
|
|
The `build_plugin_ci` performs the same tasks as `build_plugin` except that it uses a different approach for labeling
|
|
the plugin. Not all CI/CD pipelines allow docker containers to be started and connected to, something which
|
|
`build_plugin` relies on to label the plugin correctly using the plugin info specified in the plugin. `build_plugin_ci`
|
|
uses another approach which exports the image and then parses the plugin info from this image. This way a container
|
|
does not have to be started. Therefore the advantage of `build_plugin_ci` is that it can more reliably build plugins on
|
|
CI systems. The downside of this approach is that it is slower than `build_plugin` utility. It is therefore adviced to
|
|
use `build_plugin` when developing locally to speed up the development process and to use `build_plugin_ci` when
|
|
building plugins in CI/CD pipelines.
|
|
|
|
### Requirements
|
|
|
|
To build your plugin container image using `build_plugin_ci` you have to add the following line to your Containerfile
|
|
after you have copied your plugin to the image. `build_plugin_ci` requires this to find the plugin information.
|
|
|
|
<!-- pyml disable-next-line fenced-code-language-->
|
|
```
|
|
RUN plugin_info "/app/plugin.py"
|
|
```
|
|
|
|
### Command usage
|
|
|
|
`build_plugin_ci` can be invoked as follows:
|
|
|
|
```bash
|
|
build_plugin DOCKER_FILE_DIRECTORY [--target_name DOCKER_IMAGE_NAME] [--build_agent BUILD_AGENT] [BUILD_AGENT_ARGS]
|
|
```
|
|
|
|
Other than the options provided by `build_plugin` `build_plugin_ci` also provides a `--build_agent` flag which allows a
|
|
user to choose between different build agents to build and label their plugin. Currently only docker, podman and
|
|
buildah are supported. For example:
|
|
|
|
```bash
|
|
build_plugin . --target_name my-image:1.3.5 --build_agent "podman"
|
|
```
|
|
|
|
A proxy configurations can be configured as follows:
|
|
|
|
```bash
|
|
build_plugin . --build-arg http_proxy="$http_proxy" --build-arg https_proxy="$https_proxy"
|
|
```
|
|
|
|
This will generate a plugin image:
|
|
* The extraction plugin is added to your local image registry (`docker images`),
|
|
* Note that the variables `$http_proxy` and `$https_proxy` are put in quotes, this is needed in case they contain
|
|
spaces,
|
|
* The image is tagged with two tags: `latest`, and your plugin version.
|
|
|
|
Arguments:
|
|
* `DOCKER_FILE_DIRECTORY`: Path to the directory containing the Dockerfile of the plugin.
|
|
* (Optional) `DOCKER\_IMAGE\_NAME`: Name of the docker image without tag. Note that docker image names cannot start with
|
|
a period or dash. If it starts with a dash, it will be interpreted as an additional docker argument (see
|
|
DOCKER\_ARGS). If no name is given the name defaults to `extraction-plugin/PLUGINID`, e.g.
|
|
`extraction-plugin/nfi.nl/extract/chat/whatsapp`.
|
|
* (Optional) `BUILD\_AGENT`: The build agent that should be used to build the plugin. Either docker, podman or buildah.
|
|
Docker is the default.
|
|
* (Optional) `BUILD\_AGENT\_ARGS`: Additional arguments for the buildagent command, which can be as many arguments as
|
|
you like.
|