Skip to main content

Installation — overview

NomaUBL ships as a single self-contained Java application — the JAR (nomaubl.jar on Linux / macOS, nomaubl-fat.jar on Windows) plus two equivalent service-control wrappers: nomaubl.sh (Bash) and nomaubl.cmd (Windows batch). Both wrappers expose the same subcommands (start / stop / restart / status / log / install / upgrade / processing modes) and call the JAR with the same arguments — pick the one that matches your host. There's no Docker image; the JAR runs against a JDK 17 process and writes its lifecycle data to an Oracle or PostgreSQL database. The web UI, REST API and background scheduler all live inside that one process.

This section walks every step from a fresh Linux server to a running environment.

The pieces​

ComponentWhy
JDK 17The Java runtime that hosts the JAR.
DatabaseNomaUBL's persistent store — invoice lifecycle, reference data, configuration history. Oracle (19c+) or PostgreSQL (13+); same instance as your JD Edwards / SAP / NetSuite / custom ERP, or a dedicated schema.
The JARThe application binary — bundled web UI, CLI, scheduler. Shipped as nomaubl.jar (Linux / macOS) or nomaubl-fat.jar (Windows).
The wrapperA service-control script that manages the JAR lifecycle per environment and exposes shorthand forms of every CLI mode. nomaubl.sh on Linux / macOS, nomaubl.cmd on Windows.
An environment directoryPer-instance state on disk — config/, input/, process/, ubl/, single/, template/, xslt/, .versions/. Created by <wrapper> install <targetDir> (which calls -install on the JAR).
Shared resourcesOne level above the environment — fonts/ (PDF generation) and images/ (project assets). Created at install.

A single host can run multiple environments (demo, uat, prod) side by side, each with its own port and PID file.

At a glance​

NomaUBL install — from a fresh server to a running environment1 · PREREQUISITESJDK 17Oracle / PostgreSQLrequirements page2 · INSTALLnomaubl.sh install …nomaubl.cmd install …3 · CONFIGURESettings UI in browserDB · PA · connectors4 · STARTnomaubl.sh start demonomaubl.cmd start demo5 · OPSsystemd / Windows svcreverse proxy · upgradeLAYOUT PRODUCEDapp-home/ ← the JAR · the wrapper · fonts/ · images/ · demo/ · uat/ · prod/ ← one env per directoryWHAT'S NEXTSign in to the web UI on http://<host>:8090 · Configure connectors + templates · Wire your ERP source

Read in order​

StepPage
0This overview.
1Requirements — JDK, database, OS, ports, optional reverse proxy.
2Install and layout — run install, understand the directory layout, install several environments.
3Configure — start the service, sign in, configure connectors and system settings through the UI.
4Service and systemd — wrapper lifecycle, optional systemd unit (Linux) / Windows service (Windows), optional nginx reverse proxy.
5Upgrade — when a new release ships, drop the new JAR and run <wrapper> upgrade <env>.

Sanity check — what "installed" looks like​

After the four steps:

  • ./nomaubl.sh status (or nomaubl.cmd status) shows your environment(s) as running.
  • curl http://<host>:8090/api/build-info returns the version + build timestamp.
  • curl http://<host>:8090/api/license returns the license state.
  • The sign-in page renders at http://<host>:8090/.
  • The admin user you created (via the in-app Init Database step on first open) can sign in.

If any of those don't hold, the per-step page covers troubleshooting.

What this section does NOT cover​

TopicWhere it lives instead
Day-to-day CLI operations.Management → Command Line.
The web UI page-by-page.The Application / Sync / Processing / UBL Tools sections of the sidebar.
Upgrading an existing environment.Upgrade.
Live runtime observation.Monitoring.
What a "Platform Agréée" template is and how to configure one.Configuration → System → E-invoicing.

What's next​