Prepare Your Deployment#

This guide explains how to create and configure a Dioptra deployment using the cruft template system. After completing these steps, you will have a deployment folder ready to start.

Prerequisites#

  • Python 3.11+ virtual environment with the cruft package installed (pip install cruft)

  • Docker Engine and Docker Compose installed

  • Get the Container Images - Container images available (downloaded or built)

  • A terminal with access to the deployment target directory

Deployment Setup#

Step 1: Create the Deployment Directory#

Create the folder where you plan to keep your deployment and change into it so that it becomes your working directory.

mkdir -p /path/to/deployments/folder
cd /path/to/deployments/folder

Step 2: Apply the Template#

Run cruft to apply the Dioptra Deployment template. There are four different methods for configuring the deployment:

Method 1: Interactive prompts for each variable

cruft create https://github.com/usnistgov/dioptra --checkout <branch-name> \
  --directory cookiecutter-templates/cookiecutter-dioptra-deployment

Method 2: Use all default template values

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

Method 3: Use defaults except for specific values

cruft create https://github.com/usnistgov/dioptra --checkout <branch-name> \
  --directory cookiecutter-templates/cookiecutter-dioptra-deployment --no-input \
  --extra-context '{"datasets_directory": "~/datasets"}'

Method 4: Use defaults except for values in a config file

cruft create https://github.com/usnistgov/dioptra --checkout <branch-name> \
  --directory cookiecutter-templates/cookiecutter-dioptra-deployment --no-input \
  --extra-context-file overrides.json

Note

Replace <branch-name> with the Dioptra branch that matches your container images (e.g., main for releases, dev for development builds).

Tip

If you make a mistake, press Ctrl+C to interrupt cruft, remove any created folder, and start over.

Step 3: Configure Template Variables#

If you selected Method 1 (interactive prompts), you will be asked to set configuration variables. In most cases, the default value is appropriate.

Key variables include:

  • deployment_name: A name to associate with the deployment (default: Dioptra deployment)

  • container_registry: Registry prefix for Dioptra container images. Leave as default for downloaded images, or set to empty for locally built images. See Understanding Container Registry Prefixes for details. (default: ghcr.io/usnistgov)

  • container_tag: Should match the tags of your Dioptra container images (default: 1.1.0)

  • nginx_server_name: Domain name, IP address, or _ for local deployments (default: dioptra.example.org)

  • num_tensorflow_cpu_workers / num_pytorch_cpu_workers: Number of CPU workers (default: 1 each)

  • datasets_directory: Host directory to mount at /dioptra/data in workers (default: empty)

Learn More

See Deployment Template Reference for complete descriptions of all template variables, including interactive prompt examples and non-interactive configuration methods.

Step 4: Initialize the Deployment#

Run the initialization script to generate passwords, copy configuration files, and prepare the named volumes.

cd dioptra-deployment  # Or your deployment folder name
./init-deployment.sh --branch <branch-name>

Note

Replace <branch-name> with the Dioptra branch that matches your container images (e.g., main for releases, dev for development builds).

The script automates password generation, certificate bundling, volume preparation, Minio account setup, and built-in plugin syncing.

Learn More

See init-deployment.sh Script Reference for complete command-line options and detailed examples.

Step 5: Start Dioptra#

Start all Dioptra services:

docker compose up -d

Once the containers are running, open your web browser and navigate to http://localhost/ (or https://localhost/ if SSL/TLS is enabled).

Verify all services are running:

docker compose ps

Learn More

See Deployment Commands Reference for the full suite of commands to manage your deployment (stop, restart, view logs, etc.).

Next Steps#

To test that Dioptra is working, consider progressing through the Hello World Tutorial.

See Also#

How-To Guides:

Reference Documentation:

Optional Customizations: