Skip to content

Setting up the maxodiff server

Threads

The application.properties file at maxodiff/maxodiff-html/src/main/resources/application.properties contains the line

maxodiff.threads=#{T(java.lang.Runtime).getRuntime().availableProcessors() - 1}
This defaults to the number of available processors minus 1, but can be overridden. It is picked up the Spring autowiring system in the class MaxodiffController as follows:

public MaxodiffController(
        UserSessionData sessionData,
        MdContext context,
        DiffDiagRefiner diffDiagRefiner,
        @Value("${maxodiff.threads:4}") int nthreads) {
                    // ...
        }

To override this via the command line, enter 

java -jar maxodiff-app.jar --maxodiff.threads=8

To deploy the Spring Boot application inside a Docker container or via a systemd service, it is better to set an environment variable. Spring Boot automatically translates uppercase, underscore-separated environment variables into dot-notation properties. 

export MAXODIFF_THREADS=12
java -jar maxodiff-app.jar

Docker

To create the docker container

  • Start Docker
  • You many need to increase memory in the settings (in the Docker container). Choose 8gb to start if you have issues
  • Run the following command from the root project directory
docker build --no-cache -f maxodiff-html/Dockerfile -t maxodiff-html:latest .
  • To build using a proxy server, run the following command:
docker build --no-cache -f maxodiff-html/Dockerfile -t maxodiff-html:latest --build-arg http_proxy=<proxy-server-address>:<proxy-port-number> --build-arg https_proxy=<proxy-server-address>:<proxy-port-number> --build-arg MAVEN_OPTS="-Dhttp.proxyHost=<proxy-server-address> -Dhttp.proxyPort=<proxy-port-number> -Dhttps.proxyHost=<proxy-server-address> -Dhttps.proxyPort=<proxy-port-number>" .

Assuming the build runs without error, we can now start the Docker process.

  • Because your JVM heap alone requires 8GB, the total memory consumed by the container will be higher
  • Make sure the global Docker virtual machine has enough resources allocated to it. Go to Settings > Resources > Virtual manual / Advanced and ensure the memory slider is set to at least 12GB.
docker run -m 10g -p 8080:8080 --name maxodiff-html-app maxodiff-html:latest

Explanations:

  • -d: detached mode (Runs the container in the background)
  • -p 8080:8080: (Port mapping): Maps port 8080 on your host machine to port 8080 inside the Docker container.
  • --name maxodiff-html-app: Gives the running container a name so it's easy to stop or check logs later.

You should now see maxodiff-html-app in the list of Containers in the Docker GUI.

  • The docker process should now be visible at http://localhost:8080/maxodiff.

Tips

To see all processes (including exited) 

docker ps -a
CONTAINER ID   IMAGE                  COMMAND                  CREATED             STATUS                      PORTS     NAMES
7c5a93bf2bac   maxodiff-html:latest   "java -jar maxodiff-…"   About an hour ago   Exited (1) 14 minutes ago             maxodiff-html-app

  • Read the Java/Spring Boot error logs: 
    docker logs maxodiff-html-app

To remove a running container from docker 

docker rm maxodiff-html-app

  • To run in foreground -- without detach -- for debugging 
    docker run -it -p 8080:8080 --name maxodiff-html-app maxodiff-html:latest

WIPE and Rebuild Docker

  • Make changes and rebuild the app
  • Remove the old container and image trace, and rebuild the new docker image
  • Finally, restart 
    mvn clean package
docker rm maxodiff-html-app
docker rmi maxodiff-html:latest
docker build --no-cache -f maxodiff-html/Dockerfile -t maxodiff-html:latest .
docker run -it -p 8080:8080 --name maxodiff-html-app maxodiff-html:latest

Here is a script to start the server with mappings to our local directories 

#!/bin/bash
docker rm -f maxodiff-html-app 2>/dev/null
docker run -it -p 8080:8080 \
  --name maxodiff-html-app \
  -m 8g \
  -e JAVA_TOOL_OPTIONS="-Xms4g -Xmx8g" \
  -v "$(pwd)/data:/app/data" \
  -v "$HOME/maxodiff:/root/maxodiff" \
  maxodiff-html:latest

Testing with Postman

maxodiff (standard algorithm)

  • To test the container, we can use postman.
  • Use Postman Desktop app (Note: do not use the Postman Agent app, it is not suited for this).
  • Create a new request, set it to POST at http://localhost:8080/api/analyze.
  • Set the BODY to JSON and paste the JSON file for a phenopacket.
  • Click on Send.
  • The calculations will take 10 seconds, and then JSON code will be returned.

maxodiff single-disease

  • Enter POST.
  • Use the API http://localhost:8080/api/modality?targetDiseaseId=OMIM:157700. (substitute any OMIM id).
  • As body, paste in a complete phenopacket.
  • Click on SEND.
  • This will return JSON like this:
[
    {
        "targetDisease": {
            "tid": "OMIM:157700"
        },
        "maxoTerm": {
            "tid": "MAXO:0035050"
        },
        "nMaxoPhenotypes": 1,
        "totalIC": 9.061724347647399,
        "maxoScore": 8.499235179380303,
        "rankedOmimTerm": {
            "tid": "OMIM:157700",
            "averageRank": 0.0
        }
    },
    {
        "targetDisease": {
            "tid": "OMIM:157700"
        },
        "maxoTerm": {
            "tid": "MAXO:0000706"
        },
        "nMaxoPhenotypes": 2,
        "totalIC": 7.263296516746243,
        "maxoScore": 16.172687354838573,
        "rankedOmimTerm": {
            "tid": "OMIM:157700",
            "averageRank": 0.0
        }
    },
(,,,)
]