UDA-Generate - Environment Setup Steps

To set up UDA-Generate and start generating documents, a few steps must be completed to properly configure the Runtime environment. This guide walks you through the complete setup process for enabling UDF import functionality in your GenRocket environment. The setup includes downloading the runtime bundle for your platform, installing the required dependencies, and verifying the environment before your first generation.

Changelog from Last release

• Node.js 22 or newer is now required (previously 20.18.0). Node 20 will fail the preflight check.
• Python is now required for watermarking, augmentation, TIFF, EML and MSG output. A new
  python_runtime ships alongside node_runtime.
• Google Chrome or Chromium must be installed separately. UDA renders through
  puppeteer-core, which deliberately downloads no browser of its own.
• node_runtime.zip is replaced by a single platform-specific runtime bundle that contains
  both runtimes and all of their dependencies, pre-downloaded and hash-verified. Installation
  needs no internet access.
• A new --doctor command checks every dependency and tells you exactly what is missing.

Prerequisites

An internet connection is needed to download the bundle and the prerequisites above. The
installation itself is fully offline — no package registry is contacted.

Step 1 — Identify your platform

Two bundles are published. Pick the one that matches your machine before downloading.

macOS / Linux — open a terminal:

uname -s          # Darwin = macOS, Linux = Linux
uname -m          # arm64 = Apple Silicon, x86_64 = Intel/AMD
node -v           # expect v22.x or newer
python3 -V        # expect 3.14.x or 3.12.x  

Then choose your bundle:

macOS on Intel is not supported. Use an Apple Silicon Mac, a Linux host, or a Windows machine.

Step 2 — Enable Import from UDF

Ensure Import from UDF is enabled for your organization. To check simply see in new Domain section you are able to find Import from UDF option. Contact support@genrocket.com if it is not.

Step 3 — Download the UDA JAR file

1. Download the UDA Jar from the GenRocket web platform under Options ▸ Download UDA Jar.
2. Place the file in the genrocket/lib directory (the exact location varies by installation).

Common paths:

• Windows — C:\Users\<username>\genrocket\lib
• macOS / Linux — /home/users/<username>/genrocket/lib

Step 4 — Install Node.js 22 or newer

UDA renders every template through Node.js. Version 22 or newer is required; the preflight check fails on anything older.

Windows — installer

1. Download the Node.js 22 LTS Windows installer (.msi, x64) from https://nodejs.org/en/download.
2. Run the .msi and follow the wizard, accepting the default values.
3. Open a new command window and verify:

node --version  
npm --version

macOS / Linux — nvm (Node Version Manager)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

nvm install 22
nvm use 22 

Verify: 

node --version    # v22.x.x or newer
npm --version     # 10.x.x or newer

Step 5 — Install Python

Python powers watermarking, augmentation, and the TIFF / EML / MSG output formats.  

- Python 3.14 is recommended.  
- Python 3.12 is supported.
- Python 3.13 is not supported — the bundle carries no wheels for it.  
- A 64-bit interpreter is required. The installer stops on a 32-bit build.  

Windows  

1. Download the **Windows installer (64-bit)** for Python 3.14 from https://www.python.org/downloads/windows/.
2. During installation, tick “Add python.exe to PATH” and keep the py launcher enabled.  
3. Verify:  

py -3.14 -V  
py -3.14 -c "import struct; print(struct.calcsize('P') * 8)"    # must print 64

macOS

brew install python@3.14
python3.14 -V

Ubuntu / Debian

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.14 python3.14-venv
python3.14 -V

The python3.14-venv package is required — the installer creates a virtual environment.

Step 6 — Install Google Chrome or Chromium

UDA prints PDFs and images through a headless Chrome instance. The bundled renderer uses puppeteer-core, which does not download a browser, so Chrome or Chromium must already be present on the machine. Without it, generation fails and --doctor reports a FAIL.

Where UDA looks for the browser 
If the browser is at one of these paths it is found automatically:  
  
Windows

C:\Program Files\Google\Chrome\Application\chrome.exe
C:\Program Files (x86)\Google\Chrome\Application\chrome.exe
%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe
C:\Program Files\Microsoft\Edge\Application\msedge.exe

  
macOS  

/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
/Applications/Chromium.app/Contents/MacOS/Chromium
/usr/local/bin/google-chrome-stable
/usr/local/bin/chromium

Linux

/usr/bin/google-chrome-stable
/usr/bin/google-chrome
/usr/bin/chromium-browser
/usr/bin/chromium
/snap/bin/chromium

Pointing UDA at a browser elsewhere

If Chrome is installed somewhere else, set one of the following. They are checked in this order:  
 
1. chromePath in your configuration JSON  
2. the PUPPETEER_EXECUTABLE_PATH environment variable  
3. the CHROME_PATH environment variable   

export PUPPETEER_EXECUTABLE_PATH="/opt/google/chrome/chrome"
  
setx PUPPETEER_EXECUTABLE_PATH "D:\Apps\Chrome\chrome.exe"  

Note. If you set one of these overrides and the file does not exist, generation stops with
an error rather than falling back to auto-detection. Check the path carefully.

On Apple Silicon, Homebrew installs Chromium to /opt/homebrew/bin/chromium, which is not on the auto-detected list. Set PUPPETEER_EXECUTABLE_PATH if you install it that way.

Step 7 — Download the runtime bundle

Download the bundle you identified in Step 1.

Verify the download

Each bundle is published with a SHA-256 checksum. Confirm it matches before extracting.

# macOS  
shasum -a 256 uda-runtime-3.0.0-posix.zip  
  
# Linux  
sha256sum uda-runtime-3.0.0-posix.zip

Get-FileHash -Algorithm SHA256 uda-runtime-3.0.0-windows-x64.zip

Step 8 — Extract into genrocket/lib

Extract the bundle directly into the same directory as the UDA jar — normally genrocket/lib. The zip has no wrapper folder, so node_runtime and python_runtime land beside the jar, which is exactly where UDA looks for them first.

cd ~/genrocket/libunzip ~/Downloads/uda-runtime-3.0.0-posix.zip

cd $env:USERPROFILE\genrocket\lib
Expand-Archive -Path $env:USERPROFILE\Downloads\uda-runtime-3.0.0-windows-x64.zip -DestinationPath .  

The result:

genrocket/lib/  
├── gr-uda-<version>.jar          ← from Step 3  
├── node_runtime/  
│   ├── templateToPdf.js  templateToImage.js  templateToHtml.js  templateRenderer.js  
│   ├── package.json  package-lock.json  
│   ├── node_deps_sha256.csv  
│   └── npm-cache/                ← offline package cache  
├── python_runtime/  
│   ├── python_runtime.enc  
│   ├── pyproject.toml  uv.lock  requirements-delivery.txt  
│   ├── wheelhouse/               ← offline Python packages  
│   └── wheelhouse_manifest.csv  
├── sbom/                         ← CycloneDX software bill of materials  
├── install.sh   install.ps1  
├── INSTALL.md   MANIFEST.json    SHA256SUMS.txt

Step 9 — Run the installer 

From the genrocket/lib directory:  

macOS / Linux

./install.sh  

Windows (PowerShell, as Administrator)

powershell -ExecutionPolicy Bypass -File .\install.ps1

The installer checks your Node and Python versions, installs the Node dependencies from the bundled cache, builds the Python virtual environment from the bundled wheelhouse, and import-verifies both runtimes. Nothing is downloaded.

cd node_runtime
npm ci --offline --cache ./npm-cache --no-audit --no-fund 

cd ../python_runtime
python3.14 -m venv .venv
.venv/bin/python -m pip install --no-index --find-links wheelhouse \ --require-hashes -r requirements-delivery.txt

On Windows, use .venv\Scripts\python.exe in place of .venv/bin/python

Step 10 — Verify the environment

java -jar gr-uda-<version>.jar --doctor

A healthy environment looks like this:

UDA Preflight doctor
=========================
Base directory: /Users/aprilh/genrocket/lib
[ OK ] Node.js 22.19.0 (/Users/aprilh/.nvm/versions/node/v22.19.0/bin/node)
[ OK ] npm 10.9.3 (/Users/aprilh/.nvm/versions/node/v22.19.0/bin/npm)
[ OK ] node_runtime ready (/Users/aprilh/genrocket/lib/node_runtime)
[ OK ] Chrome/Chromium (/Applications/Google Chrome.app/Contents/MacOS/Google Chrome)
[ OK ] Python 3.14.3 (/opt/homebrew/bin/python3.14)
[ OK ] python_runtime venv ready (/Users/aprilh/genrocket/lib/python_runtime)
[ OK ] python_runtime.enc present

Result: READY — required dependencies satisfied.

Reading the result:

Only three checks are fatal: the Node.js version, the node_runtime folder and its installed dependencies, and Chrome/Chromium. Every Python check is advisory.

Step 11 — (Optional) Download the fonts folder for signatures

To generate PDFs with signatures using different fonts, download the fonts.zip folder. Unzip it and place it in your output directory — the path defined by resource.output.directory.

Fonts Zip Folder Link: fonts.zip

Path example

Note. You can also add your own fonts to this folder and use them when generating PDFs with signatures. Additional steps are required for adding signatures to a template in the Template Editor.

Appendix A — What each runtime provides

Basic PDF and image generation works without the Python virtual environment — --doctor will report [WARN] rather than [FAIL]. The Python-backed formats will fail until Step 9 completes successfully.

Appendix B — Troubleshoot

Do not run npm install puppeteer. The runtime pins puppeteer-core on purpose; installing the full puppeteer package pulls in a second Chromium and breaks the offline, hash-verified install.