Skip to main content
This guide gets you from zero to a running phoss SMP server using the pre-built Docker image with the XML (file-based) backend. No database setup is required.

​
Prerequisites

  • Docker installed and running
  • Port 8888 free on your machine
1

Pull and start the container

Run the official XML backend image from Docker Hub. This maps container port 8080 to host port 8888:
docker run -d --name phoss-smp -p 8888:8080 phelger/phoss-smp-xml:latest
The -d flag runs the container in the background. Tomcat starts automatically inside the container.
The recommended minimum RAM for production Docker deployments is 4 GB. For quick local testing the defaults are fine.
2

Verify the server is running

Open your browser and navigate to:
http://localhost:8888
You should see the phoss SMP start page. If the page does not load yet, wait a few seconds for Tomcat to finish starting up, then refresh.To tail the container logs:
docker logs -f phoss-smp
3

Log in to the management UI

Navigate to the secured management area:
http://localhost:8888/secure
Use the default credentials:
FieldValue
Username[email protected]
Passwordpassword
Change the default password immediately after your first login. Default credentials must never be used in a production or internet-facing deployment.
4

Run a quick smoke test

The /smp-status/ endpoint returns a JSON health summary. It is disabled by default; verify the server responds on the root path instead:
curl -s -o /dev/null -w "%{http_code}" http://localhost:8888/
Expected output:
200
You can also query a participant directly (this returns a 404 when no service groups exist, which confirms the REST layer is active):
curl -i http://localhost:8888/iso6523-actorid-upis%3A%3A0088%3A123456789
5

Persist data across restarts (optional)

The XML backend stores all data inside the container at /home/git/conf. Mount a local directory to retain data when the container is replaced:
docker run -d --name phoss-smp \
  -p 8888:8080 \
  -v "$(pwd)/smp-data:/home/git/conf" \
  phelger/phoss-smp-xml:latest
Replace $(pwd)/smp-data with any absolute path on your host.

​
Stop and remove the container

docker stop phoss-smp
docker rm phoss-smp

​
Next steps

Architecture

Understand how phoss SMP is structured: the three-layer module design, backend plugin system, and REST dispatch flow.

Configuration

Configure the keystore, identifier scheme, SML integration, and all other application properties.

Backends

Switch from the XML backend to SQL (MySQL, PostgreSQL, Oracle, DB2) or MongoDB for production use.

REST API

Explore the Peppol SMP 1.x, OASIS BDXR SMP 1.0, and BDXR SMP 2.0 REST endpoints.

Build docs developers (and LLMs) love

Get started for freeTalk to us