Skip to main content

Install flow

The installer media is small because most of DeepPhe is downloaded and assembled on the user's machine. This page walks through what the installer does, in order, as defined by the action groups in DeepPhe-and-Launcher.install4j.

1. Directory & privileges​

  • On Windows, the pipeline has an external dependency that cannot tolerate a space in the path, so the installer steers users to a no-space location (default C:\DeepPhe) and shows a warning if the chosen path contains a space.
  • The installer requests the privileges it needs and registers an Add/Remove Programs entry and program group.

2. Set installer variables​

A script inspects the OS and architecture and picks the correct launch commands, which are later written into launcher.conf:

VariablemacOS (arm64 / x64)WindowsLinux
startDpheCommandbin/runDeepPheGui.shbin/runDeepPheGui.batbin/runDeepPheGui.sh
startVizCommand./deepphe-visualizer-v2-macos-arm64 / -x64deepphe-visualizer-v2-win-x64.exe./deepphe-visualizer-v2-linux-x64
startDataApiCommand./dphe-data-api-macos-arm64 / -x64dphe-data-api-win-x64.exe./dphe-data-api-linux-x64
startDbCreatorCommand./runDpheVizDbCreator.shrunDpheVizDbCreator.bat./runDpheVizDbCreator.sh

The ontology is embedded, so the Neo4j start/stop commands are just no-op echos (DeepPhe uses embedded ontology resources.).

3. Download action group​

The installer creates the tool directories, then downloads only the binaries for the current platform from the DeepPhe-Dist releases into .DeepPhe/tools/…:

  • DeepPheVizDbCreator → .DeepPhe/tools/dphe-pipeline/
  • dphe-data-api → .DeepPhe/tools/dphe-data-api/
  • deepphe-visualizer-v2 → .DeepPhe/tools/deepphe-visualizer-v2/

It also downloads two archives:

  • DeepPhe-NLP.zip — the cTAKES/DeepPhe NLP pipeline, ontology resources, and run scripts.
  • DeepPhe-examples.zip — an example corpus and demographics.

Then it writes cross-platform wrapper scripts (runDpheVizDbCreator.sh / .bat) around the DB creator, and marks the downloaded Unix binaries executable.

See DeepPhe-Dist assets for the full URL list.

4. Unzip / extract action group​

  • Extracts DeepPhe-NLP.zip into .DeepPhe/.
  • Overlays the installer's piper files (piperfiles/, staged to .DeepPhe/piperfiles) over the pipeline definitions from the NLP zip, so the installer controls the pipeline. It also writes a DeepPheDefault.piper alias. See Piper files.
  • Extracts the ontology database jar (deepphe-onto-db2-0.7.1.jar) into .DeepPhe/resources.
  • Extracts DeepPhe-examples.zip into ~/DeepPheDocs and normalizes the example demographics JSON (wraps a top-level array in { "patients": … }).

5. Configure action group​

  • Writes launcher.conf from the per-OS variables set in step 2. This is the single file the launcher reads to know how to start each component — see Launcher.

  • Patches the NLP run scripts (runDeepPhe.sh/.bat, runDeepPheGui.sh/.bat, runDefaultGui.sh/.bat) to add the Java module options DeepPhe needs on Java 26:

    --add-exports=java.base/sun.nio.ch=ALL-UNNAMED
    --add-opens=java.base/java.lang=ALL-UNNAMED

    and makes the shell scripts executable.

  • Removes the Java 26-incompatible Log4j bridge jar (log4j-1.2-api-*) from .DeepPhe/lib; the legacy log4j-1.2.17.jar remains for cTAKES GUI classes.

  • Creates the DeepPhe Desktop projects (ProjectList.txt, ExampleProject.txt) so the GUI opens with a ready-to-run example project pointing at the example corpus and output directories.

  • Migrates old visible tool folders from previous installs: moves a legacy dphe-pipeline/output into ~/DeepPheDocs/visualizer_database/legacy_pipeline_output and cleans up known old files.

6. Cleanup & finish​

  • Deletes the leftover DeepPhe-NLP.zip / DeepPhe-examples.zip and macOS __MACOSX cruft, and removes a stale duplicate cTAKES jar.
  • Creates the DeepPhe Launcher executable and the Add/Remove entry.
  • Shows a Finished screen with links to the DeepPhe User Survey and the Release Wiki.

The result is described in Installed layout.