This step-by-step guide explains how to set up your development environment, using either Eclipse or IntelliJ for the backend and web UI and Android Studio for the mobile app. Please follow it strictly to ensure that your code adheres to our guidelines and that development will run smoothly.
Please note that these instructions are optimized for Windows and Linux systems. If you're developing on a Mac, we would be glad to get your feedback about extending this guide with OS-specific instructions through our
SORMAS Project (web application)
Please note that these instructions are optimized for Windows and Linux systems. If you're developing on a Mac, we would be glad to get your feedback about extending this guide with OS-specific instructions through our GitHub Discussions.
Step 1: Check Out the SORMAS Repository
Download and install the latest Git version for your operating system
Optional: Install a Git client such as TortoiseGit or GitHub Desktop if you don't want to handle version control from the command line or within your IDE
Optional: Clone the SORMAS-Project repository with
git clone https://github.com/sormas-foundation/SORMAS-Project.git; If you want to use Git from within your IDE, you can also clone the repository in Step 4
Open Git Bash and execute the following command to ensure that rebase is used when pulling the development branch rather than merge:
git config --global branch.development.rebase true
Step 2: Install JAVA
Download and install the Java 11 JDK (not JRE) for your operating system, which is also needed for the Server Setup. We suggest using Zulu OpenJDK. If you're running Linux, please refer to the official documentation on how to install Zulu OpenJDK on your system.
Note: To work with the Android app JDK 17 is needed for the Gradle build. The needed JDK is part of Android Studio, thus there is no need to manually install it.
The SORMAS CI is using JDK 17 to build all modules. The only known difference though is slight differences in the Java time API that affect unit tests, so again there is no need to setup two JDKs on your local system.
Step 3: Install and configure IDE
Here we can see the step-by-step process of how to set up the SORMAS project in your local environment using an Integrated Development Environment(IDE) for Developers.
IntelliJ
Reference: click here
Project repository check-out process
Download and install the latest IntelliJ IDEA Ultimate; (newer than version 2020-04-15 to enable debugging, see https://youtrack.jetbrains.com/issue/IDEA-216528)
Set the project SDK to the installed JDK.
Optional: Clone the SORMAS-Project repository if you haven't done so already.
Open the project in IntelliJ. Make sure the project is recognized by IntelliJ as a maven project; if not, right-click the pom.xml file in sormas-base and select Add as a maven project.
Make sure that under File -> Project Structure -> Modules all modules EXCEPT sormas-app are recognized; if not, add the missing modules with the + button.
Navigate to File -> Settings -> Plugins and make sure that Glassfish integration is enabled.
Make a copy of the sormas-base/dev.env.example, rename it to dev.env, and set GLASSFISH_DOMAIN_ROOT to the location of the SORMAS domain inside your Payara installation.
Run mvn install on the sormas-base project (e.g. by opening the Maven view and executing sormas-base -> Lifecycle -> install).
Alternatively, execute the dev/build.sh script. You can create a run configuration and use the Git bash executable as an interpreter to directly run it from the IDE.
Execute dev/deploy-serverlibs.sh script
Add a Payara server to IntelliJ:
Open Run -> Edit Configurations, add a new configuration and choose the Glassfish server template
Click on Configure next to the Application server and create a new server configuration by selecting your Payara installation directory
Check the After launch checkbox and specify the browser that you want SORMAS to open in once the server has been deployed
Enter http://localhost:6080/sormas-ui into the URL field
Make sure that the correct JRE is specified (your Java 11 JDK)
Enter the path to the SORMAS domain and the credentials that you've specified when setting up the server
Finally, it looks like
Open the Deployment tab and add the artifacts sormas-ear, sormas-rest, and sormas-ui (make sure to respect this order as there are dependencies between artifacts at startup)
Open the Logs tab and add a new log file pointing to the logs/server.log file in your SORMAS domain
Open the Startup/Connection tab and make sure that Pass environment variables are NOT checked; ignore warnings about the debug configuration not being correct
Open the config/domain.xml file in your domain directory and make sure that the java-config node contains the following code
<java-config classpath-suffix="" debug-enabled="true" debug-options="-agentlib:jdwp=transport=dt_socket,address=6009,server=n,suspend=y" |
Set the default working directory for run configurations by navigating to
Run -> Edit Configurations -> Templates -> Application and setting Working directory to $MODULE_WORKING_DIR$ |
Optional: Setup database access from Intellij: Open View -> Tool View -> Database, click on the + icon select DataSource -> PostgreSQL, and configure the database (set user and password and download the missing driver files if needed)
Eclipse(IDE)
Download and install the latest Eclipse IDE for Enterprise Java and Web Developers
Set the default JRE of Eclipse to the installed JDK: Assigning the default JRE for the workbench
Optional: Clone the SORMAS-Project repository if you haven't done so already via
File -> Import -> Git -> Projects from Gitand cancel the process when you're asked to create a new project from the cloned repositoryImport the projects from the SORMAS-Project repository into your workspace via
File -> Import -> Maven -> Existing Maven ProjectsInstall the Payara Tools plugin
Install the Vaadin Plugin for Eclipse; the commercial UI designer is not needed
Add a Payara server to Eclipse and enter the credentials you specified when setting up the local SORMAS server
Make a copy of
sormas-base/dev.env.example, rename it todev.envand setGLASSFISH_DOMAIN_ROOTto the location of the SORMAS domain inside your Payara installationEither run
mvn installon thesormas-baseproject or execute thedev/build.shscript (for example with Git Bash)Execute
dev/deploy-serverlibs.shscriptHighlight all Eclipse projects and choose
Maven -> Update Projectfrom the right-click menu; perform the update for all projectsStart the Glassfish server and deploy
sormas-ear,sormas-rest,andsormas-uiby dragging the respective projects onto it, or use theAdd and Remove...function by right-clicking on the server (make sure to respect this order as there are dependencies between artifacts at startup)Open your browser and type in
http://localhost:6080/sormas-uito test whether the server and IDE have been set up correctly.
Android Studio
Please note: You only need to install Android Studio if you're developing code for the Android app. This is likely the case when you're adding new fields or entities to the system, or if you specifically want to work on the mobile app.
Download and install the latest Android Studio version
Please make sure to run the installer with admin rights if you're using Windows
Ensure that the Android SDK installation path does not contain whitespaces; you can also change this later via Tools -> SDK Manager -> Android SDK Location
Open Android Studio and import the sormas-app module from the SORMAS-Project repository
Make a copy of keystore.properties.example and rename it to keystore.properties
Make sure to use the JDK version 11 (File -> Project Structure -> SDK Location -> JDK Location)
Build the Android Studio project by executing the Gradle build (this may be done automatically)
Add an emulator and set the SDK version to the minSdkVersion or targetSdkVersion from build.gradle; we suggest testing your code on both, but minSdkVersion should be preferred to ensure compatibility with the minimum supported SDK
Click on Run 'app' to install and run the app on your emulator; enter http://10.0.2.2:6080/sormas-rest as the server URL when you start the newly installed app for the first time
Important: Whenever you do or pull changes in the sormas-api project that you want to use in the mobile app or that are referenced there already, you need to execute the dev/build.sh script to notify the sormas-app project of the changes.