Skip to content

KB-211 – Packaging & Digital Signatures

Knowledge Base ID: KB-211
Project: BLACK ERP
Version: 1.0
Status: Certified
Last Updated: 2026-06-26
Applies To: ADempiere 3.9.4

Purpose

This document explains how ADempiere packages, signs and prepares the certified production runtime.

It describes the relationship between compilation, runtime packaging, digital signatures and deployment.

Understanding this process is mandatory before modifying the ADempiere Core.

Engineering Overview

The production runtime is not generated by compilation alone.

The runtime is produced through four independent stages.

Java Source
      │
      ▼
Compilation
      │
      ▼
Packaging
      │
      ▼
Digital Signing
      │
      ▼
Certified Runtime

Each stage produces a different artifact.

Stage 1 — Compilation

Compilation converts Java source code into bytecode.

Example:

source/base

↓

source/base/build

At this stage only .class files exist.

No runtime has been generated.

Stage 2 — Client Packaging

The client module assembles the compiled classes.

Command:

clientDistribute

Generated artifact:

source/lib/Adempiere.jar

Characteristics:

  • Contains compiled classes
  • Suitable for development
  • Not digitally signed
  • Does not represent the complete production runtime

Stage 3 — Runtime Packaging

Runtime packaging is performed by:

setupALib

Executed from:

source/install/build/Adempiere

This stage generates:

  • packages.jar
  • AdempiereOriginal.jar
  • Adempiere.jar

The resulting runtime contains:

  • Core classes
  • Runtime packages
  • Metadata
  • Manifest
  • Package index
  • Digital signatures

Stage 4 — Digital Signing

During runtime generation the produced JARs are digitally signed.

Signing protects the runtime from unauthorized modifications.

Typical signed files include:

META-INF/

MANIFEST.MF

INDEX.LIST

ADEMPIER.RSA

ADEMPIER.SF

Runtime Libraries

Important runtime artifacts include:

Adempiere.jar

AdempiereOriginal.jar

packages.jar

patches.jar

customization.jar

Purpose of each:

Artifact Purpose
Adempiere.jar Certified production runtime
AdempiereOriginal.jar Original runtime backup used during packaging
packages.jar Runtime package aggregation
patches.jar Runtime patches
customization.jar Customer-specific extensions

Runtime Packages

Runtime packages are merged during packaging.

Examples include:

  • Manufacturing
  • Warehouse
  • Fixed Assets
  • Freight
  • Distribution
  • Finance
  • Payroll
  • POS

These packages are required by the certified runtime.

Why setupALib is Mandatory

During the MX VAT Cash Basis implementation it was discovered that:

clientDistribute

does not generate the same runtime used by production.

The runtime produced by:

setupALib

contains additional packaging information and runtime components.

Digital Signature Validation

Typical verification command:

jarsigner -verify -verbose -certs Adempiere.jar

Expected result:

jar verified.

Warnings about self-signed certificates are expected in development environments.

SHA-256 Digest Errors

Typical error:

SHA-256 digest error

This usually indicates that a signed JAR has been modified after signing.

Typical causes:

  • Replacing classes manually
  • Updating JAR contents directly
  • Breaking META-INF integrity

The correct solution is never to modify a signed runtime directly.

Instead:

Modify source

↓

Compile

↓

Package

↓

Sign

↓

Deploy

Lessons Learned

The MX VAT Cash Basis implementation provided several important engineering findings.

  • Compilation and deployment are independent processes.
  • Runtime packaging is mandatory.
  • Production runtime is larger than the compilation artifact.
  • setupALib preserves runtime integrity.
  • Digital signatures protect runtime consistency.
  • Runtime JARs must always be regenerated instead of manually modified.

Packaging Principles

  1. Never deploy compilation artifacts directly.
  2. Never modify signed JARs manually.
  3. Always regenerate runtime packages.
  4. Always verify signatures after packaging.
  5. Always perform functional validation after deployment.

Packaging Workflow

Modify Java Source
        │
        ▼
Compile Base
        │
        ▼
clientDistribute
        │
        ▼
setupALib
        │
        ▼
Signed Runtime
        │
        ▼
Backup Production
        │
        ▼
Deploy
        │
        ▼
Restart
        │
        ▼
Smoke Test
        │
        ▼
Functional Validation

Related Knowledge Base

  • KB-208 – Core Development Lifecycle
  • KB-209 – ADempiere Runtime Architecture
  • KB-210 – ADempiere Core Debugging Guide
  • KB-212 – Accounting Engine Architecture

Revision History

Version Date Description
1.0 2026-06-26 Initial certified packaging and digital signatures guide.