PQCA CBOMkit Local Testing Environment

This project builds the CBOMkit stack from source on a fresh machine and runs it with Docker. It does not pull anything from GitHub Packages or a container registry, so one can test local code changes end to end.

Minimum System Requirements

The build compiles several Maven projects and a Vue frontend, so it needs enough memory and disk. These are the recommended minimums:

Resource	Minimum	Notes
CPU	2 cores	4 or more speeds up the Maven and npm builds
RAM	8 GB	The frontend (webpack) build is the heaviest step
Swap	2 GB	Required if RAM is at or below 8 GB, to survive build spikes
Disk	20 GB free	Maven caches, npm modules, and Docker images
OS	Linux or macOS	Any distribution with the tools below; the build detects RAM and disk automatically

Warning

On a machine with little RAM and no swap, the frontend build can exhaust memory and freeze the host, dropping your SSH session. If you have 8 GB or less, add swap before building:

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

build.sh checks memory and disk at startup and warns if either is low. It also caps the frontend build's memory to fit the available RAM.

Prerequisites

Install Java 21:

sudo apt-get update
sudo apt-get install -y openjdk-21-jdk

Install Maven:

sudo apt-get install -y maven

Install Node.js (the LTS release, using fnm here):

curl -fsSL https://fnm.vercel.app/install | bash
fnm install --lts

Install Docker and the Compose plugin:

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Add your user to the docker group so you can run Docker without sudo:

sudo usermod -a -G docker "$(whoami)"

Important

Reboot the machine after adding yourself to the docker group. The group change only takes effect after a new login.

Once the machine is back up, confirm each tool is installed:

java -version     # should report 21
mvn -version
node -version
docker version

The build expects these tools:

Tool	Expected version or path	Used for
Java 21	/usr/lib/jvm/java-21-openjdk-amd64	sonar-cryptography, cbomkit-lib, cbomkit
Maven	3.x	All Maven builds
Node.js	Current LTS	Frontend asset build
Docker	20.10+ with BuildKit	Building images and running docker compose

Note

If your Java 21 lives somewhere other than the path above, open build.sh and update JAVA_21_HOME near the top to match.

Get the Source

This repository needs to sit next to the CBOMkit source projects. They all live in the same parent folder and their names must match exactly, because build.sh finds them using ../.

Pick a parent folder and move into it:

mkdir -p ~/pqca
cd ~/pqca

Clone this repository:

git clone <cbomkit-local-testing-repo-url> cbomkit-local-testing

Clone the three required source projects into the same folder:

git clone <sonar-cryptography-repo-url> sonar-cryptography
git clone <cbomkit-lib-repo-url>        cbomkit-lib
git clone <cbomkit-repo-url>            cbomkit

The cbomkit-theia project is optional. Clone it too if you want CBOM enrichment (certificates, keys, and secrets). If you skip it, the build skips the theia proxy and everything else still works:

git clone <cbomkit-theia-repo-url> cbomkit-theia

Configure

Move into this repository:

cd ~/pqca/cbomkit-local-testing

Create your environment file from the example:

cp .env.example .env

Open .env in an editor and change any values you need. The defaults run everything on localhost, so for a plain local test you can leave the file as is. These are the settings you might change:

Variable	Default	What it does
VM_IP	localhost	The host used in the frontend URLs and the backend CORS policy. Change it to your machine's IP if you open the app from another computer.
CBOMKIT_VIEWER	false	Set to true for a read-only viewer that cannot start new scans.
JAVA_MAX_HEAP	4g	The backend JVM heap. Use 2g on an 8 GB machine, or 8g on 16 GB and up.

Warning

VM_IP is written into the frontend and the backend CORS policy when the containers start. If it does not match the address you type in the browser, the app loads but the API calls fail with CORS errors.

Align the Source Versions

Each project asks for a specific version of its sibling. If those versions do not match what the siblings build, the build fails with Could not find artifact ... in central.

Set these two versions to match their siblings before building:

• cbomkit-lib/pom.xml: set sonar.crypto.plugin.version to the version in sonar-cryptography/pom.xml (for example 2.0.0-SNAPSHOT).
• cbomkit/pom.xml: set the org.pqca:cbomkit-lib version to the version in cbomkit-lib/pom.xml (for example 1.0.0-SNAPSHOT).

Build

Make sure you are in this repository:

cd ~/pqca/cbomkit-local-testing

Run the build script:

./build.sh

The script runs these steps in order. It stops if any step fails.

Step	What happens
1	Builds sonar-cryptography with Maven and installs it locally
2	Builds cbomkit-lib with Maven and installs it locally
3	Builds the cbomkit backend with Maven
4	Copies the built JARs and the plugin into artifacts/
5	Builds the frontend assets, then builds the backend and frontend Docker images
6	Builds the optional cbomkit-theia proxy image, or skips it if that project is absent

Note

The first build downloads Maven and npm dependencies and can take several minutes. Later builds are faster.

Run

Start the whole stack in the background:

docker compose up -d

Watch the backend log and wait until it is ready:

docker compose logs -f backend

The backend is ready when you see this line:

Listening on: http://0.0.0.0:8081

Press Ctrl+C to stop watching the log. The containers keep running.

Open the app in your browser:

Service	Address
Frontend	http://localhost:8002
Backend API	http://localhost:8082
PostgreSQL	localhost:5433

Rebuild After Changes

When you change code in any of the source projects, rebuild the images and restart the stack:

cd ~/pqca/cbomkit-local-testing
./build.sh
docker compose down
docker compose up -d

Cleanup

Stop the stack but keep the database data:

docker compose down

Stop the stack and delete all data, including the database volumes:

docker compose down -v