👊Quick start

Installation of the app

How to download and install The MEDiml Application

Below are tutorials for downloading and installing the app on various operating systems.

These tutorials are currently outdated and will be updated soon. In the meantime, please follow the instructions below.

Windows

Ubuntu

MacOS

The MEDiml application architecture

MEDiml follows the same architechture of its mother application. This visual guide is designed to support new contributors in understanding the application’s structure, streamlining the integration of new features, and aiding efficient navigation through the codebase.

Contribute to MEDiml-App🌱

1. Prerequisites

1.1 Installation of MongoDB Community Edition

Windows

Install MongoDB on Windows

• Do not install MongoDB as a service.

• You do not have to install MongoDB Compass.

• You do not have to install mongosh.

• Do not forget to add MongoDB binaries to the System PATH.

Linux

MacOS

1.2 Installation of MongoDB database tools

Windows

Install with the MSI Installer.

Linux

MacOS

2. Node.js and NVM Setup

2.1 Installation of Nvm

• NVM for Windows

• NVM for Ubuntu/MacOS

2.2 Installation of npm/node.js

nvm install lts
nvm use lts

---

Be careful, the next steps are different depending on the user's privilege.

---

For members of the MEDomicsLab GitHub Organization.

3. Clone the Repository

Using HTTPS:

git clone -b develop https://github.com/MEDomicsLab/MEDiml-app.git

Using SSH:

git clone -b develop [e-mail]:MEDomicsLab/MEDiml-app.git

4. Backend Setup (Go)

4.1 Install Go

1. Download the latest stable release of Go from the official website: https://golang.org/dl/

2. Follow the installation instructions for your operating system.

4.2 Setup of environment

Execute these commands in the terminal:

Windows:

setx GOPATH %USERPROFILE%\go
setx PATH "%PATH%;C:\Go\bin"

Linux/MacOS:

echo 'export PATH=$PATH:/usr/local/go/bin' >> $HOME/.bashrc
echo 'export GOPATH=$HOME/go' >> $HOME/.bashrc
echo 'export PATH=$PATH:$GOPATH/bin' >> $HOME/.bashrc

After, close all your terminals because these commands will take effect on the initialization of any terminal

4.3 Verify installation

In a new terminal, run:

go version

If Go is installed correctly, you should see the version number printed to the console.

4.4 Setup for the application

cd <repo-path>/go_server
go run main.go   # initial run installs dependencies

Next, build the executable:

go build main.go

Rebuild after any .go file modification.

5. Create Your Own Branch

Always branch from develop, and ensure you have the latest changes:

git checkout develop
git pull origin develop
git checkout -b your-branch-name
# push your branch to MEDiml-app repository
git push --set-upstream origin your-branch-name

6. Make Changes

• Follow the project structure

• Keep commits small and descriptive

git add .
git commit -m "feat: add new feature X"

Commit naming conventions:

• feat: new feature

• fix: bug fix

• docs: documentation changes

• refactor: code restructuring

• test: tests added/updated

---

7. Push Changes

git push

---

8. Create a Pull Request

1. Go to the MEDiml-app GitHub Pull Requests page

2. Click New Pull Request

3. Target branch: develop

4. Compare branch: your-branch-name

---

9. Pull Request Guidelines

Ensure:

• ✅ Code compiles and runs

• ✅ No console errors

• ✅ Proper formatting

• ✅ Tests pass (if applicable)

• ✅ Clear PR description:

  • What was done

  • Why was it done

  • Screenshots (if UI changes)

---

10. Code Review Process

• Address reviewer comments

• Push updates to the same branch

• Keep discussion professional and concise

11. After Merge

git checkout develop
git pull
git branch -d feature/your-feature-name # Time for a new feature

For external users

🌱 Contributing via Fork (Common Practice)

This workflow is recommended for external contributors.

---

3. Fork the Repository

1. Go to the official repo

2. Click Fork

3. Clone your fork:

git clone https://github.com/<your-username>/MEDimage-app.git
cd MEDimage-app

---

4. Add Upstream Remote

git remote add upstream https://github.com/MEDomicsLab/MEDimage-app.git

Verify:

git remote -v

---

5. Create a Feature Branch

Always branch from develop:

git fetch upstream
git checkout develop
git pull upstream develop

git checkout -b feature/your-feature-name

---

6. Backend Setup (Go)

6.1 Install Go

1. Download the latest stable release of Go from the official website: https://golang.org/dl/

2. Follow the installation instructions for your operating system.

6.2 Setup of environment

Execute these commands in the terminal:

Windows

setx GOPATH %USERPROFILE%\go
setx PATH "%PATH%;C:\Go\bin"

Linux/MacOS

echo 'export PATH=$PATH:/usr/local/go/bin' >> $HOME/.bashrc
echo 'export GOPATH=$HOME/go' >> $HOME/.bashrc
echo 'export PATH=$PATH:$GOPATH/bin' >> $HOME/.bashrc

After, close all your terminals because these commands will take effect on the initialization of any terminal

6.3 Verify installation

In a new terminal, run:

go version

If Go is installed correctly, you should see the version number printed to the console.

6.4 Setup for the application

cd <repo-path>/go_server
go run main.go   # initial run installs dependencies

Next, build the executable:

go build main.go

Rebuild after any .go file modification.

---

7. Make Changes

• Follow the project structure

• Keep commits small and descriptive

git add .
git commit -m "feat: add new feature X"

Commit naming conventions:

• feat: new feature

• fix: bug fix

• docs: documentation changes

• refactor: code restructuring

• test: tests added/updated

---

8. Sync with Upstream

Before pushing:

git fetch upstream
git rebase upstream/develop

---

9. Push Changes

git push origin feature/your-feature-name

---

10. Create a Pull Request

1. Go to your fork on GitHub

2. Click Compare & Pull Request

3. Target branch: develop (base repo)

---

11. Pull Request Guidelines

Ensure:

• ✅ Code compiles and runs

• ✅ No console errors

• ✅ Proper formatting

• ✅ Tests pass (if applicable)

• ✅ Clear PR description:

  • What was done

  • Why was it done

  • Screenshots (if UI changes)

---

12. Code Review Process

• Address reviewer comments

• Push updates to the same branch

• Keep discussion professional and concise

---

13. After Merge

git checkout develop
git pull upstream develop
git branch -d feature/your-feature-name

---

Running the Electron App

Launch the Electron application (desktop app window) and start the required development servers (frontend/backend):

cd <repo_path/MEDiml-app>
npm install
npm run dev

Worth noting

On Windows, if you encounter error messages when running npm installrelated to tensorflow .dll files missing, revert your node version by following these steps:

• Download node v18.16.1

• Add to the PATH variable the path to your new node placing it higher than the old node.

• Test your node version using: node --version

MongoDB configuration

MEDiml-app uses port 54017 as the default MongoDB connection port. For database visualization and management, we recommend using MongoDB Compass, the official GUI client from MongoDB.

Key Details:

• Default Port: 54017

• Recommended Client: MongoDB Compass

• Connection String Format: mongodb://localhost:54017/

Modify startup settings

1. Go to file medomics.dev.js

2. Here is a description of the Object:

export const PORT_FINDING_METHOD = {
  FIX: 0,
  AVAILABLE: 1
};

const config = {
  // Automatically starts the backend server when the app launches
  runServerAutomatically: true,

  // Enables React Developer Tools (useful for debugging UI)
  useReactDevTools: false,

  // Default port used by the Electron/Go server
  defaultPort: 54288,

  // MongoDB connection port
  mongoPort: 54017,

  // Port allocation strategy:
  // FIX        -> Forces use of defaultPort (terminates conflicting processes if needed)
  // AVAILABLE  -> Finds the next available port if defaultPort is occupied
  portFindingMethod: PORT_FINDING_METHOD.FIX
};

export default config;

Testing Production Builds

Build & Run

This compiles the application code and packages the Electron app into an executable format:

Windows

npm run build:win                            # build and package the application 
.\build\dist\win-unpacked\MEDiml-app.exe    # Run the executable of the built version

Linux

MacOS

The built app will be located in the build/dist folder.

Now that the app is live and running, it is time to learn how to use the interface. See you on the next page. 😉