Custom Worker Template Reference#

This reference describes the template variables and generated files for the custom Dioptra worker cookiecutter template.

See also

Create a Custom Worker Container - Step-by-step guide for creating a custom worker container.

Template Variables#

When running cookiecutter interactively, you will be prompted to set the following variable.

project_name#

Default: Custom Dioptra Worker

A name for your custom worker project. The template converts this name to a slug (lowercase, spaces and underscores replaced with hyphens) and uses it as the generated folder name. For example, My NLP Worker produces a folder named my-nlp-worker.

Interactive Prompt Example#

When running cookiecutter interactively, you will see a prompt like the following. The value between the square brackets [] shows the default answer. Press Enter to accept the default, or type a new value.

project_name [Custom Dioptra Worker]: My NLP Worker

Tip

If you make a mistake during the prompt, you can interrupt cookiecutter by pressing Ctrl+C. If cookiecutter has already created a folder, remove it before starting over.

Non-Interactive Configuration#

To skip the interactive prompt, use --no-input and pass variable values directly.

Note

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

Use the default project name:

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

Override the project name:

cookiecutter https://github.com/usnistgov/dioptra --checkout <branch-name> \
  --directory cookiecutter-templates/custom-dioptra-worker --no-input \
  project_name="My NLP Worker"

Generated Folder Structure#

The following tree shows all files created by the template. The folder name is derived from the project_name variable.

my-nlp-worker/
├── ca-certificates/
│   └── README.md
├── configs/
│   └── aws-config
├── shellscripts/
│   ├── entrypoint-worker.m4
│   ├── healthcheck-worker.m4
│   └── wait-for-it.sh
├── Dockerfile
└── requirements.txt

Dockerfile#

Multi-stage Docker build file that produces the custom worker image. The build process:

  1. Installs system packages and configures the locale.

  2. Bundles any CA certificates placed in ca-certificates/.

  3. Compiles shell script templates (*.m4 files) into executable scripts using argbash.

  4. Creates a Python virtual environment and installs the packages listed in requirements.txt.

  5. Assembles the final image with the worker entrypoint, health check, and virtual environment.

The image is compatible with both amd64 and arm64 platforms and defaults to the host platform when building.

requirements.txt#

Lists the Python packages to install in the worker’s virtual environment. Must include dioptra-platform as a dependency. Add additional packages here to make them available to the worker at runtime.

ca-certificates/#

Place custom CA certificate files (.crt, PEM format) in this directory if the build environment requires them. See the README.md inside this directory for details.

These certificates are used only during the Docker build process and are not included in the final image at runtime.

configs/#

aws-config

AWS CLI configuration file copied to ~dioptra/.aws/config in the final image. Sets the default AWS region (us-east-1), output format (json), and S3 signature version (s3v4). This is required for the worker to communicate with the S3-compatible storage backend (MinIO).

shellscripts/#

Shell script templates that are compiled during the Docker build.

entrypoint-worker.m4

Template for the container’s entrypoint script. The compiled script waits for dependent services (Redis, MinIO, database, REST API) to become available, then starts the dioptra-worker-v1 process.

healthcheck-worker.m4

Template for the container’s health check script. The compiled script verifies that the dioptra-worker-v1 process is running.

wait-for-it.sh

Utility script that tests TCP connectivity to a host and port. Used by the entrypoint script to wait for services before starting the worker.

See Also#