2 update code base

.gitignore

@@ -1,3 +1,51 @@
-*/target
+#
+# NOTICE
+# 
+# This software (or technical data) was produced for the U. S. Government 
+# and is subject to the Rights in Data-General Clause 52.227-14, Alt. IV 
+# (May 2014) – Alternative IV (Dec 2007)
+# 
+# (c) 2024 The MITRE Corporation. All Rights Reserved.
+# 
+
+# IAT Items
 .DS_Store
-.env
+docker/.env
+*/target/*
+jet/
+
+# Web Directories
+web/client/.angular/
+web/client/dist/
+web/client/node_modules/
+
+# Acii Directories
+acii/acii-client/logs/
+acii/acii-client/build/
+
+# Inference Directories
+inference/logs/
+inference/__pycache__/
+inference/*.out
+inference/*.png
+inference/*.sh
+
+# BIQT Directories
+biqt/build/
+biqt/.idea/
+biqt/*.iml
+biqt/target/
+
+# Tshepii Directories
+tshepii/build/
+tshepii/.idea
+
+# PDM Directories
+pdm/__pycache__/
+pdm/models/
+pdm/modules/__pycache__/
+pdm/data/
+pdm/.DS_Store
+pdm/.env
+pdm/*venv*
+pdm/pdm-models*

README.md

@@ -1,150 +1,127 @@
-# NOTICE #
+>
+> NOTICE
+>
+> This software (or technical data) was produced for the U. S. Government and is subject to the Rights in Data-General Clause 52.227-14, Alt. IV (May 2014) - Alternative IV (Dec 2007).
+>
+> (c) 2024 The MITRE Corporation. All Rights Reserved.
+>
 
-Only artifacts necessary for running the containerized version of the Iris Analysis Tookit stack are currently available. Code will be published soon. Please see [Quickstart for Users](#quickstart-for-users) below for running the software with `Docker`.
 
-# Iris Analysis Toolkit #
+# Iris Analysis Toolkit
 
 The Iris Analysis Toolkit (IAT), formerly known as the Iris Workstation and Iris Workstation Prototype, is a system that demonstrates the capabilities of an iris examination workstation. It was made to allow users to easily create generic Electronic Biometric Transmission Specification files as well as review and annotate iris images.
 
-## Table of Contents ##
+## Table of Contents
 
 - [Iris Analysis Toolkit](#iris-analysis-toolkit)
   - [Table of Contents](#table-of-contents)
   - [Software Versions](#software-versions)
+  - [Build Everything from Source](#build-everything-from-source)
   - [Quickstart for Users](#quickstart-for-users)
-  - [QuickStart for Developers](#quickstart-for-developers)
-    - [MacOS Installation](#macos-installation)
-    - [Start Up](#start-up)
 
-## Software Versions ##
+## Software Versions
 
-This program was built using these package managers, but may work with newer versions:
+This project was built with the following tools and may work with newer versions:
 
-- Development Platform: Angular Cli -v 17.3.1
-- Runtime Environment: node -v >= 20.15.0
-- Angular Package Manager: npm -v 10.8.1
-- Java SE Environment: java -v 17
-- Build Package: maven -v 3.9.6
+- Development platform: Angular CLI 17.3.1
+- Runtime environment: Node.js 20.15.0 or later
+- Angular package manager: npm 10.8.1
+- Java SE environment: Java 17
+- Build tool: Maven 3.9.6
+- JavaScript package manager: Yarn 1.22.22
 
-## Quickstart for Users ##
+## Build Everything from Source
 
-This section gives steps to start the program for users who are simply looking to run the application (i.e., are not troubleshooting or developing). Since this section only runs docker containers, it doesn't run any changes made on the local environment.
+Use the provided build script to build every IAT component from a clean source checkout. The script builds the public JET and BIQT dependencies, packages the Maven modules, downloads the PDM models, and builds local CPU Docker images for ACII, BIQT, Iris Annotation, TSHEPII, PDM, and the Web component.
 
-1. Start Up Project
-   1. **IMPORTANT!** The `docker compose` files in the `iwp-simple` directory will use credentials from a `.env` file in that directory. For security reasons, a `.env` file is not included  in this repo. To use the `docker compose` files you will need to create a `.env` file in the `iwp-simple` directory with the following contents:
-
-		DATABASE_PASSWORD=A_STRONG_PASSWORD_OF_YOUR_CHOOSING
-		DATABASE_USERNAME=A_USERNAME_OF_YOUR_CHOOSING
-		DATABASE_ROOT_PASSWORD=ANOTHER_STRONG_PASSWORD_OF_YOUR_CHOOSING
+### Prerequisites
 
-      See [this link](https://docs.docker.com/compose/environment-variables/set-environment-variables/#compose-file) for details about .env files 
-   2. In the terminal, type the following commands to start up docker containers:
+- Docker with BuildKit enabled. Docker Desktop users should enable Linux/AMD64 emulation when building on Apple Silicon.
+- Git, Java 17, Maven, and Bash.
+- Internet access to clone public dependencies and download Maven, Python, PDM-model, and container-image dependencies.
+- Enough disk space for Maven caches, model files, and Docker build layers.
 
-    ```bash
-    cd iris-workstation/iwp-simple/ #Navigates into to the subdirectory that contains the docker scripts for easy running
-    ./composeScript.sh prune #Clear out old/unwanted data and unused containers, images, etc:
-    docker compose up #Runs the docker script for easy start up
-    ```
-
-2. Use Project
-   1. Open choice of web browser and navigate to `localhost:8080`
-      1. Log in with username and password
-   2. Start generating and annotating files
-
-## QuickStart for Developers ##
-
-This section gives steps to start the program in the "editing mode". The following steps are for developers who are troubleshooting or contributing to the code. This section starts up the program to run only the services in docker containers. The backend and frontend parts are built and ran using the code from the local environment.
-
-### MacOS Installation ###
-
-Follow the steps below to get started with this project's development environment on a Mac.
-
-1. Install Xcode Command Line Tools
-   1. Open Terminal and type the following command:
+If your network uses a TLS-inspecting proxy, provide its PEM root certificate with `IAT_CA_FILE`. The script passes the certificate to image builds as a BuildKit secret so the affected build stages can add it to their trust stores.
 
-        ```bash
-        xcode-select --install
-        ```
+### Build
 
-   2. In the new dialog windows, confirm and agree to the installation and license agreement
-2. Install Homebrew
-   1. Open Terminal and type the following command:
+From the repository root, run:
 
-        ```bash
-        /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-        ```
+```sh
+./scripts/build-all.sh
+```
 
-   2. Type your admin password and hit Enter[^1]
-   3. Wait a few minutes until you see a "Installation successcul" message
-    [^1]: You won't see your keystrokes in the terminal
-3. Install Packages
-    - Open Terminal and type the following commands to install the packages:
+For a TLS-inspecting network, run:
 
-    ```bash
-    brew install angular-cli #Angular Cli
-    brew install node@20.15.0 #Node
-    brew install maven #Maven
-    ```
-
-### Start Up ###
-
-1. Clone Project
-2. Start Up Project:
-   1. In the terminal, type the following commands to start up the docker containers:
-
-        ```bash
-        cd iris-workstation/iwp-simple/ #Navigates into to the subdirectory that contains the docker scripts for easy running
-        ./composeScript.sh prune #Clear out old/unwanted data and unused containers, images, etc.
-        docker compose -f docker-compose.local.yml up #Runs a docker script that only starts up the services from docker containers
-        ```
+```sh
+IAT_CA_FILE=/path/to/organization-root-ca.pem ./scripts/build-all.sh
+```
 
-   2. Open a second terminal window and type the following commands to start up the backend:
+The script clones the public dependencies into a sibling `iat-dependencies/` directory by default. Set `IAT_DEPENDENCY_ROOT` to use another location. It tags the local images with the same names and versions used by `docker/docker-compose.yml`, so Docker Compose uses the images you just built. The default target platform is `linux/amd64`, matching the Compose configuration.
 
-		**After this step you can access the application at [http://localhost:8080](http://localhost:8080).**
+The script builds the CPU Iris Annotation image. To build the GPU variant instead, run the equivalent command after the script completes:
 
-        ```bash
-        cd iris-workstation/ #Navigates to the project's home directory
-        UNIX: export JASYPT_ENCRYPTOR_PASSWORD="examplepass"
-        Windows: $Env:JASYPT_ENCRYPTOR_PASSWORD ="examplepass"
-        ./iwp-script.sh full #Runs the local backend services, including any changes just made
-        ```
+```sh
+docker build -t ghcr.io/mitre/iat/iwp-annotation:26.08 \
+  -f inference/core/Dockerfile-GPU inference/core
+```
 
-   3. **(Optional)** Open a third terminal window and type the following commands to start up the frontend:
+After the build completes, create `docker/.env` from `docker/.env.template`, provide strong non-empty credentials and a database name, and start the local images with `docker compose up` from `docker/`.
 
-		**You only need this step if you want access to a front end that automatically refreshes when changes are made.**
-
-		After this step you can access the front end development server at [http://localhost:4200](http://localhost:4200).
+## Quickstart for Users
 
-		**Special note about the front end development server:** Due to some Spring Security and webpack-dev-server proxy complexities, the login page does not work through the development server. You likely will see strange and broken behavior on the front end development server. There are two workarounds for this:
+This section explains how to start the application for users who only need to run it and are not troubleshooting or developing. Because it runs only Docker containers, local source-code changes are not included.
 
-		- Disable the login page while doing front end development by setting `iwp.security.secured=false` in the `application.properties` file.
+### Set up Environment Variables
+1. Start the project.
+   **Important:** The Docker Compose files in the `docker` directory and the `application.properties` files in the `web` directory use credentials from a `.env` file in the `docker` directory. For security reasons, the repository includes only a `.env.template` file. To run the application with Docker or locally, follow these steps:
+   1. Make a new file in the `docker` directory called `.env` from the `.env.template` file by running:
+      ```sh
+      cp .env.template .env
+      ```
+   2. Set the variables in the new `.env` file to usernames and passwords of your choosing. The database and Artemis passwords do not need to be encrypted.
+
+See the [Docker documentation](https://docs.docker.com/compose/environment-variables/set-environment-variables/#compose-file) for details about `.env` files.
 
-		- Go to the front end hosted by the Java backend [http://localhost:8080](http://localhost:8080) and login there. Requests through the front end development server [http://localhost:4200](http://localhost:4200) should then be authenticated. 
+*Note: User-role passwords must be BCrypt hashes encrypted with Jasypt. Follow the next step to prepare them.*
 
-        ```bash
-        cd iris-workstation/client/ #Navigates to the project's front end subdirectory
-        yarn run local #Runs the local frontend services, including any changes just made
-        ```
+2. Prepare user-role passwords.
+   1. Create a BCrypt hash of the password. The following command uses a temporary Docker container and prints only the hash. Replace `YOUR_PASSWORD` with the password to use:
+      ```sh
+      bcrypt_hash="$(docker run --rm httpd:2.4-alpine \
+        htpasswd -bnBC 12 '' 'YOUR_PASSWORD' | cut -d: -f2)"
+      printf '%s\n' "$bcrypt_hash"
+      ```
+   2. Download and unpack the [Jasypt command-line tool](http://www.jasypt.org/cli.html). If the ZIP download is unavailable, see the [Jasypt releases](https://github.com/jasypt/jasypt/releases). From the unpacked Jasypt directory, encrypt the BCrypt hash with the value assigned to `JASYPT_ENCRYPTOR_PASSWORD` in `docker/.env`:
+      ```sh
+      ./bin/encrypt.sh input="$bcrypt_hash" password="$JASYPT_ENCRYPTOR_PASSWORD" algorithm=PBEWITHHMACSHA512ANDAES_256 verbose=true stringOutputType=base64 providerName=SunJCE saltGeneratorClassName=org.jasypt.salt.RandomSaltGenerator ivGeneratorClassName=org.jasypt.iv.RandomIvGenerator
+      ```
+      Quoting `"$bcrypt_hash"` preserves the `$` characters in the BCrypt value.
+   3. Set the appropriate password variable in `docker/.env` to the encrypted output, wrapped in `ENC(...)`. For example:
+      ```dotenv
+      DEFAULT_USER_PASSWORD=ENC(123abcENCRYPTEDpass)
+      ```
+      Repeat these steps for `DEFAULT_REVIEWER_PASSWORD` and `DEFAULT_SUPERVISOR_PASSWORD`.
 
-   4. **(Optional)** Open a fourth terminal window and type the following commands to start up the database management container:
+   Default users are created only when the application initializes an empty database. If containers have already initialized the database with incorrect passwords, changing `.env` does not update those accounts. For a disposable local installation, recreate the database before starting the application:
+   ```sh
+   docker compose down
+   docker volume rm docker_my-db
+   docker compose up
+   ```
+   This permanently deletes the local IAT database volume and its data.
 
-		**You only need this step if you want to access the database for debugging purposes.**
+### Run Application via Docker
+The following steps start the application in user mode. This mode runs published containers and does not include local source-code changes. To run local changes, follow the [Run Application From a Script](web/README.md#from-a-script) instructions in the `web/` subdirectory.
 
-        ```bash
-        cd iris-workstation/ #Navigates to the project's home directory
-        docker run --name iwp_php_admin --network iwp-simple_default -v phpmyadmin-volume:/etc/phpmyadmin/config.user.inc.php --link iwp_mysql:db -p 82:80 -d phpmyadmin/phpmyadmin #Runs the database container
+*Note: To use a GPU for the Iris Annotation component, comment out the CPU `iwp-annotation` Docker service and uncomment the GPU service in `iat/docker/docker-compose.yml`.*
 
-3. Use Project
-    1. Open choice of web browser and navigate to `localhost:4200`
-       1. Log in with username and password
-    2. To see the database, open choice of web browser and navigate to `localhost:82`
-       1. Log in with username and password
-
+The default Compose deployment exposes only the web application. ActiveMQ Artemis and MySQL remain on the internal Docker network. Use `docker-compose.local.yml` for local development; its broker and database ports bind only to `127.0.0.1`.
 
-## NOTICE
-
-#### Approved for Public Release; Distribution Unlimited. Public Release Case Number 23-1989
-
-#### This software (or technical data) was produced for the U. S. Government and is subject to the Rights in Data-General Clause 52.227-14, Alt. IV (May 2014) – Alternative IV (Dec 2007)
+1. In a terminal, run the following commands in the `iat/docker/` subdirectory:
+    ```sh
+    ./composeScript.sh prune # Removes unused containers, images, and other data.
+    docker compose up # Starts the services and user interface with Docker Compose.
+    ```
 
-#### (c) 2024 The MITRE Corporation. All Rights Reserved.
+2. In a web browser, navigate to `http://localhost:8080` and log in with your configured username and password.

acii/Dockerfile

@@ -0,0 +1,26 @@
+#
+# NOTICE
+# 
+# This software (or technical data) was produced for the U. S. Government
+# and is subject to the Rights in Data-General Clause 52.227-14, Alt. IV 
+# (May 2014) – Alternative IV (Dec 2007)
+# 
+# (c) 2026 The MITRE Corporation. All Rights Reserved.
+# 
+FROM alpine:3.23
+
+COPY acii /acii
+COPY buffers/src/main/proto /buffers/src/main/proto
+
+WORKDIR /acii/install
+
+# Building on some infrastructure requires the installation of a certificate authority. This is OPTIONAL
+# for external systems and will only be installed when the ca_file secret is provided in the build command.
+RUN --mount=type=secret,id=ca_file,required=false \
+    if [ -f /run/secrets/ca_file ]; then \
+       cat /run/secrets/ca_file >> /etc/ssl/certs/ca-certificates.crt; \
+    fi
+
+RUN ./install.sh && rm -rf /acii /buffers /apache-log4cxx-* /activemq-cpp-library-* /opencv-*
+
+CMD [ "aciiComponent", "/etc/iwp-acii/acii.conf", "/etc/iwp-acii/logger.conf", "false", "/var/log/acii.log" ]

acii/README.md

@@ -0,0 +1,61 @@
+>
+> NOTICE
+>
+> This software (or technical data) was produced for the U. S. Government and is subject to the Rights in Data-General Clause 52.227-14, Alt. IV (May 2014) - Alternative IV (Dec 2007).
+>
+> (c) 2024 The MITRE Corporation. All Rights Reserved.
+>
+
+
+# ACII Component
+
+The ACII component is an Iris Analysis Toolkit (IAT) service that analyzes an iris image and returns its orientation, including whether the iris is left or right.
+
+## Starting the Service
+This service can be started in two ways:
+1. (Recommended) [Docker Image via the IAT](#docker-and-iat)
+2. [From a Script](#from-a-script)
+
+If you make changes to the scripts and want to create a new Docker image, see [Rebuild Docker Image](#rebuild-docker-image).
+
+### Docker and IAT
+This is the recommended way.
+To start the service with Docker through the IAT interface, follow the [Quickstart for Users](../README.md#quickstart-for-users) instructions.
+
+
+### From a Script
+#### Prerequisites
+- A Linux environment with `sudo` access. The installation script supports Alpine and APT-based distributions.
+- A C++17 compiler, CMake, Make, Autotools, and Curl.
+- Protocol Buffers version 3 or later, Apache ActiveMQ-CPP, Apache Log4cxx, APR, and OpenCV 2.4.
+- An ActiveMQ-compatible broker reachable from the ACII service.
+
+The installation script installs or builds the required native dependencies and builds the ACII client.
+
+```sh
+cd acii/install
+sudo ./install.sh
+```
+
+#### Starting the Script
+Once you have completed the prerequisites, follow these steps:
+1. Start an instance of ActiveMQ and note the username and password you configure.
+2. Replace `temp_value` for `artemis-user` and `artemis-password` in `acii-client/config/acii.conf` with the values from step 1.
+3. Run ACII with the following command:
+    ```sh
+    /usr/local/bin/aciiComponent /etc/iwp-acii/acii.conf /etc/iwp-acii/logger.conf false /var/log/acii.log
+    ```
+
+The ACII client is now running. It consumes messages from `iris.acii.request` and produces messages on `iris.acii.response`.
+
+*Note: This option is not recommended because a client must publish an `ImageServiceQuery` message to ActiveMQ on `iris.acii.request` and consume the resulting `AciiServiceResponse` message from `iris.acii.response`. A client script is not currently provided.*
+
+## Rebuild Docker Image
+To build a new Docker image, run this command from the main `iat/` project directory:
+  ```sh
+  # Remove `--secret` argument if organization certificate does not need to be installed.
+  # `--platform linux/amd64` is required when building on Apple Silicon systems.
+  DOCKER_BUILDKIT=1 docker build --platform linux/amd64 -t new_acii_image:YOUR_TAG_HERE \
+  --secret id=ca_file,src=ca_file.crt \
+  -f acii/Dockerfile .
+  ```