Detailed Installation Guide - OxalisCommunity/oxalis-ng GitHub Wiki

Table of Contents

Prerequisites Checklist Installation Steps Alternate Standalone Setup Testing and verifying your installation Sending a sample invoice to your own local access point Sending a sample invoice to Remote access point

Prerequisites

  • Java JDK 11+ (and higher versions)
  • Maven 3+ (if you plan to build Oxalis yourself)
  • Tomcat 10+ (if you have a different JEE container, you need to figure out the differences on your own, sorry :-) )
  • Create OXALIS_HOME directory to hold configuration files, certificates etc
  • Add OXALIS_HOME environment variable to reference that directory

All of these must be installed properly, i.e. make sure the binaries are available from your command line.

Checklist

When running the following commands you should expect output similar to the one shown

Verify Command Expected example output
JDK 11 javac -version javac 11.0.25
Maven 3 mvn -version Apache Maven 3.8.6
OXALIS_HOME echo $OXALIS_HOME in unix OR echo %OXALIS_HOME% in Windows /usr/arunk/.oxalis OR C:/OXALIS_HOME

Installation Steps

  1. Install Tomcat and configure it for SSL on port 443 or make sure you terminate SSL in front of Tomcat on port 443 (using nginx or similar). Please, do not change this port. Most other access points need to communicate with you and their operations department usually don't like opening non-standard ports. CAUTION: Do not use your Peppol AP certificate as an SSL certificate

  2. Obtain latest Oxalis-NG binary artifacts either by:

    • Downloading latest binary artifacts from Maven Repo and unpack the distribution OR
    • Downloading latest binary artifacts from GitHub Release

  3. Create an Oxalis home directory in which you place files that do not change between new releases of Oxalis. We recommend that you name the Oxalis home directory .oxalis in what is considered the home directory of the user running Oxalis

  4. Remember to set the $OXALIS_HOME environment variable referencing your Oxalis home directory in your shell startup script. Example: export OXALIS_HOME=~/.oxalis

  5. See the Get and Configure Peppol AP Certificate for details on how to install or replace the Peppol certificate. During the startup, your certificate validated towards the proper certificate chain. Please note that Oxalis will not work non-Peppol or expired certificates

  6. Create the file oxalis.conf. Here is an example of how it might look:

     oxalis.keystore {
     # Relative to OXALIS_HOME
     path=POP000XXX_Test_AP.p12
     password = "<SOME-PASSWORD>"
     key.alias = cert
     key.password = "<SOME-PASSWORD>"
 }

# Configure logging configuration file 
oxalis.logging.config = logback.xml

# Where to store inbound files
 oxalis.path.inbound = /var/peppol/IN

    Additional configuration information can be found in the Configuration Guide

  7. Copy the file oxalis-ng.war into your Tomcat deployment directory, example:

    cp oxalis-dist/oxalis-ng-distribution/target/oxalis-ng-distribution-x.y.z/jee/oxalis-ng.war $CATALINA_HOME/apache-tomcat-10.1.33/webapps

  8. Start Tomcat, check the logs for any errors and make sure the oxalis status page seems right (the URL could be different based on your own setup). Note: If you intend to terminate TLS in your Tomcat instance, the status pages reside at https://localhost/oxalis-ng/status

  9. Attempt to send a sample invoice using below command to your local access point setup:

    java -jar oxalis-ng-distribution-1.0.0-distro\bin\oxalis-ng-standalone.jar -f Sample.xml -u http://localhost:8080/oxalis-ng/as4 --cert /path/to/your/POP000XXX_Test_AP.cer

Alternate Standalone Setup

You can find additional/alternate way to configure Standalone (Inbound & outbound) at Standalone Setup Details

Testing and verifying your installation

Testing and verification of your installation assume that you have performed above listed actions.

  • You have obtained a Peppol Test AP Certificate. The running mode will be automatically detected by Oxalis-NG by validating your AP certificate.

Sending a sample invoice to your own local access point

You need to override the use of the SML/SMP in order to send directly to your own access point. This is done by specifying the URL and providing public key of AP certificate

Here is how to send a sample invoice to your own local access point:

java -jar oxalis-ng-distribution-1.0.0-distro\bin\oxalis-ng-standalone.jar -f Sample.xml -u http://localhost:8080/oxalis-ng/as4 --cert /path/to/your/POP000XXX_Test_AP.cer

Sending a sample invoice to Remote access point

This is how you send a sample invoice to remote test access point using the test SML (SMK):

java -jar oxalis-ng-distribution-1.0.0-distro\bin\oxalis-ng-standalone.jar -f Sample.xml

Make sure endpoint exists and support respective profile. Verify that your sample invoice received at remote destination access point.

Good luck!!!