Create a Custom Worker Container#

This guide walks through creating a custom Dioptra worker container using the provided cookiecutter template. A custom worker lets you include Python packages or other software that is not available in the standard Dioptra worker images.

Prerequisites#

Custom Worker Creation#

Step 1: Generate the Project#

Run cookiecutter to generate a new project from the custom worker template:

cookiecutter https://github.com/usnistgov/dioptra \
  --checkout <branch-name> \
  --directory cookiecutter-templates/custom-dioptra-worker

Replace <branch-name> with the Dioptra branch that matches your deployment (e.g., main for releases).

You will be prompted for a project name. The name you provide is used to create the project folder (converted to lowercase with hyphens).

project_name [Custom Dioptra Worker]: My NLP Worker

This creates a folder named my-nlp-worker/ containing the files needed to build a custom worker image. See the Custom Worker Template Reference for a full description of the generated files.

Step 2: Add Python Dependencies#

Open requirements.txt in the generated project folder. By default it contains only dioptra-platform, which is required for the worker to function:

dioptra-platform

Add any additional Python packages your worker needs. For example, to include the textattack package:

dioptra-platform
textattack

Note

The dioptra-platform package must remain in requirements.txt. It provides the worker process and task engine that Dioptra requires.

Step 3: Build the Docker Image#

From inside the generated project folder, build the Docker image:

cd my-nlp-worker
docker build -t my-nlp-worker:dev .

Choose an image name and tag that you will recognize when configuring your deployment.

Note

If your build environment requires custom CA certificates (for example, in a corporate network that intercepts HTTPS traffic), see the ca-certificates/README.md file in the generated project for instructions.

Step 4: Verify the Image#

Confirm the image was built successfully:

docker images | grep my-nlp-worker

You should see the image listed with the tag you specified.

Advanced Customization#

The template is designed for users who need to add Python packages to the worker environment. If you need to install operating system packages, add scripts, or include other files in the container, you can edit the Dockerfile directly.

See Also#