Skip to content

Migrations

Jump to bottom
Philip Helger edited this page Dec 10, 2023 · 34 revisions

Note: all upgrades from one micro version to another micro version (as in 5.7.1 → 5.7.2), using the same major and minor version (5.7 in the previous example), should be "drop-in replacements", except noted otherwise.

Upgrade from 7.0 to 7.1

Nothing to do. The primary reason for the minor version bump is the update to support Peppol SMP specification 1.3.0 (SHA-256).

Upgrade from 6.0 to 7.0

The minimum requirement to run phoss SMP is Java 11. It runs with Java 17 and Java 21 as well.

Also an update from JavaEE to JakartaEE 9 was performed which means, that at least Apache Tomcat v10.0.x or Jetty 11.x are required to run phoss SMP.

Upgrade from 5.7 to 6.0

General

The configuration system has been updated, so that system properties and environment variables can be used to configure parts of the system. The resolution of the new configuration file is described at https://github.com/phax/ph-commons/wiki/ph-config

Now the content of all the previous configuration files should be merged into the single file application.properties. Just copy all the lines from webapp.properties and smp-server.properties and append it to the existing application.properties. If you don't have application.properties but only pd-client.properties (which was obsoleted ages ago in v5.3 and is no longer supported in v6.x) then first rename pd-client.properties to application.properties and then append the contents of the other files. The old files webapp.properties and smp-server.properties can be removed. For the sake of backwards compatibility, the old files are still read - this feature will be removed in the next major release.

Note: the default encoding of the files changed from ISO-8859-1 to UTF-8.

The following system properties are no longer supported and their existence will lead to a startup error:

  • peppol.smp.server.properties.path
  • smp.server.properties.path
  • peppol.smp.webapp.properties.path
  • smp.webapp.properties.path

The following environment variables are no longer supported and their existence will lead to a startup error:

  • SMP_SERVER_CONFIG
  • SMP_WEBAPP_CONFIG

Note: for backwards compatibility, the old files with the old names will still be read - this feature will be removed in the next major release.

The following configuration properties, that are the defaults for the settings, have been renamed:

  • sml.needed → sml.required
  • sml.active → sml.enabled
  • smp.peppol.directory.integration.required → smp.directory.integration.required
  • smp.peppol.directory.integration.enabled → smp.directory.integration.enabled
  • smp.peppol.directory.integration.autoupdate → smp.directory.integration.autoupdate
  • smp.peppol.directory.hostname → smp.directory.hostname

Support for Vagrant has been removed. Docker support is untouched.

SQL backend

Flyway has been updated to the latest version v9.x which does not support MySQL 5.7 anymore. Please see the Flyway Release Notes for all details.

XML backend

Nothing to do

MongoDB backend

Nothing to do

Upgrade from 5.6 to 5.7

General

  • The name of the configuration properties for SMP client proxy configuration changed. See https://github.com/phax/peppol-commons#configuration for details.
    • http.proxyHost is now http.proxy.host
    • http.proxyPort is now http.proxy.port
    • http.proxyUsername is now http.proxy.username
    • http.proxyPassword is now http.proxy.password
    • http.nonProxyHosts is now http.proxy.nonProxyHosts
    • http.useSystemProperties is now deprecated
  • The name of the configuration properties for Directory client configuration changed. See https://github.com/phax/phoss-directory#client-configuration-properties for details.
    • keystore.type is now pdclient.keystore.type
    • keystore.path is now pdclient.keystore.path
    • keystore.password is now pdclient.keystore.password
    • keystore.key.alias is now pdclient.keystore.key.alias
    • keystore.key.password is now pdclient.keystore.key.password
    • truststore.type is now pdclient.truststore.type
    • truststore.path is now pdclient.truststore.path
    • truststore.password is now pdclient.truststore.password
    • http.proxyHost is now http.proxy.host
    • http.proxyPort is now http.proxy.port
    • proxy.username is now http.proxy.username
    • proxy.password is now http.proxy.password
    • connect.timeout.ms is now http.connect.timeout.ms
    • request.timeout.ms is now http.request.timeout.ms
    • https.proxyHost is no longer supported
    • https.proxyPort is no longer supported

SQL backend

All the necessary changes should be performed automatically using Flyway. If you disabled Flyway make sure, your database is compliant to V19 (5.7.0) of the scheme.

This version ships with initial support for DB2. This DB system is still considered experimental, so handle with care.

See these folders for the DDL scripts:

Upgrade from 5.5 to 5.6

SQL backend

All the necessary changes should be performed automatically using Flyway. If you disabled Flyway make sure, your database is compliant to V17 (5.6.0) of the scheme.

See these folders for the DDL scripts:

XML backend

Nothing to do

MongoDB backend

Nothing to do

Upgrade from 5.4 to 5.5

SQL backend

All the necessary changes should be performed automatically using Flyway. If you disabled Flyway make sure, your database is compliant to V14 (5.5.0 and 5.5.1) or V15 (5.5.2+) of the scheme.

See these folders for the DDL scripts:

XML backend

Nothing to do

MongoDB backend

Nothing to do

Upgrade from 5.3 to 5.4

SQL backend

All the necessary changes should be performed automatically using Flyway. If you disabled Flyway make sure, your database is compliant to V3 of the scheme.

See these folders for the DDL scripts:

XML backend

Nothing to do

MongoDB backend

Nothing to do

Upgrade from 5.2 to 5.3

General

Before upgrading to 5.3, please make sure that you have 5.2.x running. An update from previous versions may have unexpected side effects.

  • When using the environment variable DIRECTORY_CLIENT_CONFIG to locate the pd-client.properties file:
    • you need to instead use the environment variable CONFIG_FILE and the file should be renamed to application.properties
  • When using the system property peppol.pd.client.properties.path or pd.client.properties.path to locate the pd-client.properties file
    • you need to instead use the system property config.file and the file should be renamed to application.properties
  • Note: the goal of these preparations is to harmonize the configuration system of the SMP, so that future versions only use a single configuration file.

SQL backend

  • The SQL backend was changed from EclipseLink to native JDBC.
  • Additionally FlyWay was introduced for SQL version management. This creates a new table flyway_schema_history and needs CREATE, DROP, INDEX and ALTER rights for the database user.
  • Additionally PostgreSQL was added as a new supported database system
  • The database table "smp_user" is removed, and all users are integrated into the "internal" user management. Due to internal requirements the usernames needed to be changed. The old name abc was automatically transformed to abc@example.org. The password was taken over unchanged - compared to the DB table it is now only stored as a hash value. This login name can be easily edited under "Administration | Security | User management". So if you are using the REST API to communicate with the SMP please make sure to use the updated user name for authentication.

XML backend

Nothing to do

MongoDB backend

Nothing to do

Upgrade from 5.0 or 5.1 to 5.2

General

The names of the WAR files changed:

  • peppol-smp-server-webapp-sql → phoss-smp-webapp-sql
  • peppol-smp-server-webapp-xml → phoss-smp-webapp-xml

SQL backend

An update of the database structure is necessary. Please see the DDL instructions in https://github.com/phax/phoss-smp/blob/master/phoss-smp-backend-sql/database_backups/update-5.2.0-mysql.sql

ALTER TABLE `smp_service_metadata_redirection` ADD COLUMN `certificate` LONGTEXT NULL;
ALTER TABLE `smp_service_metadata_redirection` MODIFY `certificateUID` VARCHAR(256) NULL;

For DB2:

ALTER TABLE smp_service_metadata_redirection ADD COLUMN certificate CLOB NULL;
ALTER TABLE smp_service_metadata_redirection ALTER COLUMN certificateUID DROP NOT NULL;

Hint for DB2: it is suggested to REORG your tables afterwards (see http://publib.boulder.ibm.com/infocenter/db2e/v9r1/index.jsp?topic=%2Fcom.ibm.db2e.doc%2Fsqlreorgt.html)

Basically a new column is added, and another column is made nullable.

The file https://github.com/phax/phoss-smp/blob/master/phoss-smp-backend-sql/database_backups/smp_mysql_20200220_v5.2.x.sql is an "all-inclusive" file to be used for new users of phoss-smp 5.2.x for MySQL.

The file https://github.com/phax/phoss-smp/blob/master/phoss-smp-backend-sql/database_backups/smp_postgresql_20200820_5.2.x.sql is an "all-inclusive" file to be used for new users of phoss-smp 5.2.x for PostgreSQL.

XML backend

Nothing to do

Upgrade from v5.0 to v5.1

Nothing to do

Upgrade from v5.0.x to v5.0.4 or newer

It must be ensured that the new truststore (truststore/complete-truststore.jks) containing OpenPeppol v2 and v3 certificates is used.

Upgrade from v5.0.0 to v5.0.1

The name of the WAR file changed. peppol-smp-server-webapp-X.Y.Z was changed to either peppol-smp-server-webapp-xml-X.Y.Z.war or peppol-smp-server-webapp-sql-X.Y.Z.war (depending on the backend you want to use). This was because of some weird application server logic in combination with EcliseLink JAR.

Upgrade from v4.x to v5.0

To upgrade from version 4.x of the SMP to version 5.x of the SMP, please consider the following aspects:

  • Version 5 of the SMP server requires Java 8 both for development as well as for runtime. That means that also at least Tomcat 7 is recommended for execution.
  • When using the sql backend, another table must be added to the database. For MySQL, use the following DDL:
DROP TABLE IF EXISTS `smp_bce`;
CREATE TABLE `smp_bce` (
 `id` varchar(45) NOT NULL COMMENT 'Internal ID',
 `pid` varchar(255) NOT NULL COMMENT 'Participant/Business ID',
 `name` text NOT NULL COMMENT 'Entity name',
 `country` varchar(3) NOT NULL COMMENT 'Country code',
 `geoinfo` text COMMENT 'Geographical information',
 `identifiers` text COMMENT 'Additional identifiers',
 `websites` text COMMENT 'Website URIs',
 `contacts` text COMMENT 'Contact information',
 `addon` longtext COMMENT 'Additional information',
 `regdate` date DEFAULT NULL COMMENT 'Registration date',
 PRIMARY KEY (`id`),
 KEY `FK_pid` (`pid`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1 COMMENT='SMP Business Card Entitiy';
  • There are a couple of new Configuration items in version 5 which may require customization. For all configuration items sensible default values are used so there is usually no need to change anything. See Configuration for all the details.
    • smp.truststore.path: The classpath - relative to the project - where the Java trust store (of type JKS) with the public certificates of the SMLs to communicate with are contained. This property is optional. If no trust store path is provided, the SML client caller trusts all SML https certificates.
    • smp.truststore.password: The password used to access the truststore.
    • smp.identifiertype: determine the identifier types to be used.
    • smp.rest.type: this property determines the layout of the REST responses.

It is appreciated if you star the GitHub project if you like it.

Donation link: https://paypal.me/PhilipHelger

Logo

Clone this wiki locally