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.
Before you can start you need to have the following information in place:
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!
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.
/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.
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:
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).
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.
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.
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.
Please refer to the Wiki at https://github.com/phax/phoss-smp/wiki/Security for the best practices on securing the SMP.
Now that your new SMP server is up and running, you should perform some setup tasks.
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.
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.
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
}