Skip to main content

​
General upgrade process

1

Read the release notes and migrations wiki

Before upgrading, check the phoss SMP Migrations wiki page for version-specific actions. Some releases require manual steps that cannot be automated.
2

Back up your data

  • XML backend: copy the entire webapp.datapath directory.
  • SQL backend: take a full database dump.
  • MongoDB backend: use mongodump.
  • Also back up your application.properties and keystore files.
3

Stop the running instance

Shut down Tomcat or the Docker container before swapping the WAR/image.
4

Deploy the new version

Replace the WAR file in $CATALINA_HOME/webapps/ or pull and restart the new Docker image (see Docker upgrade).
5

Apply any configuration changes

Compare your application.properties against the new default configuration. New properties added in the release will use their built-in defaults unless you explicitly set them.
6

Start and verify

Start the server and check the logs for errors. Confirm the management UI loads and the /ping/ endpoint returns HTTP 200.

​
Database schema migrations (SQL backend)

The SQL backend uses Flyway 12 to manage schema versioning. Migration scripts live in: 
phoss-smp-backend-sql/src/main/resources/db/migrate-{mysql,postgresql,oracle,db2}/
Migrations run automatically on startup — no manual SQL execution is needed. Flyway compares the current schema version with the bundled scripts and applies any that are missing.
Flyway requires that the database user has ALTER TABLE, CREATE TABLE, and CREATE INDEX privileges in addition to the usual DML privileges.

​
Notable SQL migration

The migration ID sql.db-users-to-regular-users (defined in CSMPServerMigrations) handles the one-time transition from the legacy database-level user model to the regular phoss SMP user model. This migration runs automatically the first time you start a version that includes it.

​
XML backend

XML data files are forward-compatible across minor and patch versions. No schema migration is required when upgrading between patch releases. For major version upgrades, the startup code applies any necessary in-place migrations to the XML files automatically. Check the Migrations wiki to confirm whether a specific major upgrade requires manual steps.

​
MongoDB backend

MongoDB collections are schema-less. Structural changes are handled by the startup code at runtime. No manual migration steps are required for most upgrades. Check the Migrations wiki for any exceptions.

​
Docker image upgrade

1

Pull the new image

docker pull phelger/phoss-smp-xml:latest
# or for SQL:
docker pull phelger/phoss-smp-sql:latest
2

Stop and remove the old container

docker stop phoss-smp
docker rm phoss-smp
3

Start a new container with the same volumes and config

docker run -d \
  --name phoss-smp \
  -p 80:8080 \
  -v /etc/smp/config:/config \
  phelger/phoss-smp-xml:latest
Your application.properties, keystore, and data directory are preserved via the mounted volume.
4

Verify startup

docker logs -f phoss-smp
Watch for INFO startup messages and the absence of ERROR entries. Confirm with:
curl -f http://localhost/ping/

​
Key breaking changes in recent versions

​
v8.0 — Java 17 requirement

Starting with v8.0, phoss SMP requires Java 17 or later. Java 11 is no longer supported. Verify your JVM before upgrading: 
java -version
The output must show version 17 or higher. Update your container base image or JDK installation if needed.

​
v6.0.7 — Bearer token authentication

v6.0.7 introduced Bearer token authentication as the preferred method for REST API calls. Existing Basic Auth integrations continue to work without any changes, but new integrations should use tokens created under Administration > Security > User Tokens. See Authentication for details.

​
Configuration file changes between versions

New properties are added periodically. Check the default application.properties in the new WAR (or the phoss-smp-webapp-xml, phoss-smp-webapp-sql, or phoss-smp-webapp-mongodb module) against your deployed file. The safest approach is to diff your running configuration against the default: 
diff application.properties.new application.properties.current
Properties that are missing from your file will use their default values, but it is good practice to review them explicitly.

​
Notable property additions

VersionPropertyDefaultDescription
v8.0.11jdbc.pooling.max-connections8DBCP2 max pool size
v8.0.11jdbc.pooling.max-wait.millis10000DBCP2 max borrow wait
v8.0.6smp.rest-remote-query-api.enabledfalseRemote Query API toggle
v8.0.2smp.publicurl.moderequestPublic URL detection strategy
v5.7.0webapp.nicename.doctypes.path—Doc type nice-name XML path
v5.7.0webapp.nicename.processes.path—Process nice-name XML path
v5.2.0smp.rest.log.exceptionsfalseLog REST exceptions

​
Backup recommendations

Always take a backup immediately before upgrading. Even automatic migrations are irreversible without a backup if something goes wrong.

​
XML backend

# Backup the entire data directory
tar -czf smp-data-backup-$(date +%Y%m%d).tar.gz /var/smp/

​
SQL backend

# MySQL example
mysqldump -u smp -p smp > smp-backup-$(date +%Y%m%d).sql

# PostgreSQL example
pg_dump -U smp smp > smp-backup-$(date +%Y%m%d).sql

​
Configuration files

cp application.properties application.properties.bak
cp keystore/smp.p12 keystore/smp.p12.bak

Build docs developers (and LLMs) love

Get started for freeTalk to us