Setup phoss SMP

This page explains how to setup my implementation (phoss SMP) of an PEPPOL SMP from scratch. SMP is the abbreviation for Service Metadata Publisher which is the decentralized directory service (registry) of OpenPeppol. SMPs are normally only operated by Service Providers and not by end users. An SMP contains information about the endpoints of receivers - the URLs where to send the main documents to. The information within the SMP is structured by participant ID, document type ID and process ID.

phoss SMP is a fork of the CIPA e-Delivery SMP components on version 2.2.3 back in 2015. The goal is to keep the implementation simple and provide publicly available PEPPOL components to the world. An additional goal was to make the configuration as simple as possible. Please read the official phoss SMP Wiki for all the details.

Prerequisites

Before you can start you need to have the following information in place:

  1. As the very first step you need to sign the TIAs (Transport Infrastructure Agreements) with OpenPeppol AISBL
  2. Afterwards you need to apply for an SMP certificate at OpenPeppol. This certificate is required to run the SMP.
  3. You should have a look at the official SMP specifications. It is important to understand that the specifications only specify the reading access to an SMP but not the writing access. Nevertheless the implementation discussed here also contains the possibility to write new entries.
  4. You should be familiar with Java 1.8+
  5. When using the SMP server implementation with a database backend basic knowledge of a relational database (e.g. MySQL) is required. Alternatively a filesystem based XML backend is also available.
  6. Basic knowledge about Apache Tomcat or Jetty (and optionally a web server) should be present

Technical resources

My phoss SMP server implementation is located on GitHub at phax/phoss-smp. It contains the source code and a Wiki with the relevant documentation. The SMP server uses shared components also available on GitHub: peppol-commons - a common library with shared PEPPOL components containing e.g. an SMP client library and an SML client library.

The sources and the binary resources are available on GitHub:

Pre-build Docker images are available on hub.docker.com:

See https://github.com/phax/phoss-smp/wiki/Source for the description of the different source modules. All of the components are available as ready-to-use Maven projects.

Hint when using Eclipse: it is best to close the project in Eclipse when a commandline build is performed because otherwise Eclipse might want to refresh while the console build is in progress. After the build finished you may re-open the project in Eclipse and clean it there again, because the Eclipse compiler and the Oracle console compiler produce incompatible byte code for enumeration classes!

phoss-smp-webapp-[mongodb|sql|xml]

This is the main SMP server application logic. It is provided as a Java web application that can be deployed in an application server like Apache Tomcat or Jetty.

The SMP service has been implemented as a REST interface with a customizable backend that stores the data.

  • phoss-smp-webapp-sql uses a relational database as its backend. A copy of the MySQL database initialization script can be found in the /database_backups/ folder of the project. By default a user peppol_user with the password Test1234 is created! The database layout is compatible to the one of the CIPA SMP 2.2.x.
  • phoss-smp-webapp-xml uses XML files as its backend. smp-servicegroup.xml stores all the service groups, smp-servicemetadata.xml stores all the service metadata associated to the service groups and smp-redirect.xml stores all the service redirects related to a service group. Additional files for user management etc. are also used.

The application can be deployed in two ways:

  • Compiling the project on the command line using mvn clean install. The result is a WAR file in the target folder and additionally an exploded version of the WAR file in the target/phoss-smp-webapp-[sql|xml|mongodb]-x.y.z directory (where x.y.z denotes the version number).
  • Run the application src/test/java/com/helger/phoss/smp/standalone/RunInJettySMPSERVER_[SQL|XML|MONGODB] from within your IDE. Than the application will be running on localhost port 90 (not 80!) and can be accessed with a browser or an SMP client.
Note that a production SMP service MUST be deployed as the ROOT web application (at path "/") on the application server, since this is a prerequisite in the DNS lookup scheme. Furthermore it MUST be deployed on port 80 (standard http port) and may not use SSL to secure the transport.

Configuring the SMP server

The SMP server is configured with two files. One file (webapp.properties) is for the customization of the web application and the other file (smp-server.properties) is for the SMP functionality itself. Additionally a PEPPOL Directory client file (pd-client.properties) may be configured. Please read the Wiki page https://github.com/phax/phoss-smp/wiki/Configuration for all configuration options and example files.

Security considerations

Please refer to the Wiki at https://github.com/phax/phoss-smp/wiki/Security for the best practices on securing the SMP.

Initialization

Now that your new SMP server is up and running, you should perform some setup tasks.

  • Change the default user admin@helger.com with the default password password to something more complex! This can be easily achieved by logging into the URL http://yourserver/secure and use the Change password page to perform the change.
  • When using the SQL backend, change the default DB user peppol_user with the default password Test1234 to something more complex! This can be easily achieved on the management page "DB users" or by altering the content of the database table smp_user manually. After this change, simply provide the new credentials for writing operations.
  • The SMP must be registered at the SML. For this purpose an online tool is integrated in this page to perform this task.

peppol-smp-client

This is the default Java library to query any SMP server (that is compliant to the specifications) for participant information. The client library has the sole purpose to provide reusable functionality. It does not offer executable functionality itself. The code base of this in a different repository than the SMP server, it is located at https://github.com/phax/peppol-commons.

The com.helger.peppol.smpclient.SMPClient is the main class when using the library. The class contains methods for reading, saving and deleting both service groups and service metadata, as well as listing the service groups of a given user. The writing methods of this class can only be used in conjunction with phoss SMP server as for different implementations the write access may have been implemented in a different way (if provided at all). Alternatively the class com.helger.peppol.smpclient.SMPClientReadonly can be used to access any SMP that complies to the SMP specifications. The library contains both static and non-static methods for performing all of these actions. The class is documented using JavaDoc.

Note: the classes SMPClientReadonly and SMPClient can only be used to query SMPs that follow the old PEPPOL SMP specification. To query an SMP server that follows the OASIS BDXR SMP v1 specification the classes BDXRClientReadonly and BDXRClient are provided with a similar API.

The following is an example code of getting a service metadata object of a service group (participant) for a certain document type:

    // ServiceGroup = participant identifier; GLN = 0088
    final IParticipantIdentifier aServiceGroupID = EPredefinedIdentifierIssuingAgency.GLN.createParticipantIdentifier ("5798000000001");
    // Document type identifier from enumeration
    final IDocumentTypeIdentifier aDocumentTypeID = EPredefinedDocumentTypeIdentifier.INVOICE_T010_BIS4A.getAsDocumentTypeIdentifier ();
    // Main call to the SMP client with the correct SML to use
    final SignedServiceMetadataType aMetadata = SMPClientReadOnly.getServiceRegistrationByDNS (PeppolURLProvider.INSTANCE,
                                                                                               ESML.DIGIT_TEST,
                                                                                               aServiceGroupID,
                                                                                               aDocumentTypeID);
    if (aMetadata == null)
    {
      // No such metadata
    }
    else
    {
      // Evaluate metadata
    }
  

You must be logged in to post a comment!