Skip to content

docs: update installation guide for React–backend integration #238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: installation-doc
Choose a base branch
from
Open

docs: update installation guide for React–backend integration #238

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
192 changes: 115 additions & 77 deletions docs/Installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,67 +8,77 @@ _**NOTE:**_
* make sure you are logged in as user with sudo permissions

### Step 1: Install prerequisite

sudo apt-get update
sudo apt-get install -y python3 python3-pip gcc git python3-dev libssl-dev libffi-dev cron python3-lxml apache2 libapache2-mod-wsgi-py3
sudo pip3 install cffi cryptography Flask launchpadlib simplejson requests pytest
```bash
sudo apt-get update
sudo apt-get install -y python3 python3-pip gcc git python3-dev libssl-dev libffi-dev cron python3-lxml apache2 libapache2-mod-wsgi-py3
sudo pip3 install cffi cryptography Flask launchpadlib simplejson requests pytest
Copy link
Contributor

@pleia2 pleia2 Oct 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With this command on Ubuntu 24.04, I get an error:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
python3-xyz, where xyz is the package you are trying to
install.

If you wish to install a non-Debian-packaged Python package,
create a virtual environment using python3 -m venv path/to/venv.
Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
sure you have python3-full installed.

If you wish to install a non-Debian packaged Python application,
it may be easiest to use pipx install xyz, which will manage a
virtual environment for you. Make sure you have pipx installed.

See /usr/share/doc/python3.12/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

How did you work around this?

Following the suggestion from this error message, I used these packages instead installed via apt:

python3-cffi python3-cryptography python3-flask python3-launchpadlib python3-simplejson python3-requests python3-pytest

Copy link
Contributor

@pleia2 pleia2 Oct 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also needed:

python3-flask-cors python3-dotenv

```

* if "/usr/local/bin" is not part of $PATH add it to the path:

echo $PATH
export PATH=/usr/local/bin:$PATH
sudo sh -c "echo 'export PATH=/usr/local/bin:$PATH' > /etc/profile.d/alternate_install_path.sh"
```bash
echo $PATH
export PATH=/usr/local/bin:$PATH
sudo sh -c "echo 'export PATH=/usr/local/bin:$PATH' > /etc/profile.d/alternate_install_path.sh"
```

### Step 2: Checkout the source code, into /opt/ folder

cd /opt/
sudo git clone https://github.com/openmainframeproject/software-discovery-tool.git
cd software-discovery-tool

```bash
cd /opt/
sudo git clone https://github.com/openmainframeproject/software-discovery-tool.git
cd software-discovery-tool
```

Note: In case software-discovery-tool code is already checked out, do the following for latest updates

cd /opt/software-discovery-tool
sudo git pull origin master
```bash
cd /opt/software-discovery-tool
sudo git pull origin master
```

### Step 3: Set Environment variables

sudo sh -c "echo 'export PYTHONPATH=/opt/software-discovery-tool/src/classes:/opt/software-discovery-tool/src/config:$PYTHONPATH' > /etc/profile.d/software-discovery-tool.sh"

```bash
sudo sh -c "echo 'export PYTHONPATH=/opt/software-discovery-tool/src/classes:/opt/software-discovery-tool/src/config:$PYTHONPATH' > /etc/profile.d/software-discovery-tool.sh"
```

### Step 4: Install and configure software-discovery-tool

#### Copy the apache configuration file from `/opt/software-discovery-tool/src/config/sdt.conf` into respective apache configuration folder as below

sudo cp -f /opt/software-discovery-tool/src/config/sdt.conf /etc/apache2/sites-available/sdt.conf
sudo mv /etc/apache2/sites-available/000-default.conf /etc/apache2/sites-available/z-000-default.conf
```bash
sudo cp -f /opt/software-discovery-tool/src/config/sdt.conf /etc/apache2/sites-available/sdt.conf
sudo mv /etc/apache2/sites-available/000-default.conf /etc/apache2/sites-available/z-000-default.conf
```


#### Create new user and group for apache

sudo useradd apache
sudo groupadd apache

```bash
sudo useradd apache
sudo groupadd apache
```

#### Set appropriate folder and file permission on /opt/software-discovery-tool/ folder for apache

sudo chown -R apache:apache /opt/software-discovery-tool/
```bash
sudo chown -R apache:apache /opt/software-discovery-tool/
```

#### Start/Restart Apache service

sudo apachectl restart
```bash
sudo apachectl restart
```

### Step 5: Cloning Data Directory (Only First Time)
openmainframeproject/software-discovery-tool-data contains all OMP created json files. To add the data files, we will use `git submodule`
- map the submodule directory with the directory path and update the directory:
```
```bash
sudo -u apache git submodule update --init --recursive --remote
```

#### Updating Data Directory
Everytime there's an upstream change in the submodule:
- To update the data directory with the main repo with the remote changes:
```
```bash
sudo -u apache git pull <upstream remote> <default branch> --recurse-submodules
```
- To update ONLY the data directory keeping the main repo as it is:
```
```bash
sudo -u apache git submodule update --recursive --remote
```

Expand All @@ -78,7 +88,7 @@ The data directory we cloned above only brings in sources maintained by this pro

For example, taking RHEL_8_Package_List.json
- Usage help will be displayed:
```
```bash
cd /opt/software-discovery-tool/bin
./package_build.py
Usage:
Expand All @@ -92,7 +102,7 @@ Example:
./package_build.py RHEL_8_Package_List.json
```
Example of extracting the RHEL_8_Package_List.json from PDS repo:
```
```bash
sudo -u apache ./bin/package_build.py RHEL_8_Package_List.json
Extracting RHEL_8_Package_List.json from PDS data ...
Thanks for using SDT!
Expand All @@ -101,7 +111,7 @@ Thanks for using SDT!
- Make sure the json file exists in the PDS data directory.
- Please keep in mind that the directory belongs to user `apache`, so in case of permission error,
run the chown cmd or directly use `package_build.py` as `apache` user like:
```
```bash
sudo -u apache ./bin/package_build.py RHEL_8_Package_List.json
```

Copy link
Contributor

@pleia2 pleia2 Oct 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's update below this line to mention the src/config/supported_distros.py.example file, text with something like:

Copy src/config/supported_distros.py.example to src/config/supported_distros.py to tell SDT where to find the sources:

sudo -u apache cp  src/config/supported_distros.py.example src/config/supported_distros.py

And then continue to the section that says "The src/config/supported_distros.py must now be updated to reflect..." since I believe all of that is fine.

Expand All @@ -113,24 +123,37 @@ The `src/config/supported_distros.py` must now be updated to reflect the new jso
### Step 6: Install and populate the SQL database

#### Install dependencies and complete the secure installation. Remember the root password you set, you will need this in the future.
```bash
sudo apt install mariadb-server python3-pymysql
sudo mysql_secure_installation
```

sudo apt install mariadb-server python3-pymysql
sudo mysql_secure_installation
***NOTE:***
- If you encounter the following error when running `sudo mysql_secure_installation`:
```bash
Enter current password for root (enter for none):
ERROR 2002 (HY000): Can't connect to local server through socket '/run/mysqld/mysqld.sock' (2)
```
It means the MariaDB service is not running. Start it with:
```bash
sudo service mariadb start
```

#### Log in to MariaDB with the root account you set and create the read-only user (with a password, changed below) and database.
```bash
# Log in to MariaDB with the root account you set.
mariadb -u root -p

# Log in to MariaDB with the root account you set.
mariadb -u root -p

# Create the read-only user
MariaDB> CREATE USER 'sdtreaduser'@'localhost' IDENTIFIED BY 'SDTUSERPWD'; # Replace 'SDTUSERPWD' with the desired password.
# Create the read-only user
MariaDB> CREATE USER 'sdtreaduser'@'localhost' IDENTIFIED BY 'SDTUSERPWD'; # Replace 'SDTUSERPWD' with the desired password.

# Grant permissions.
MariaDB> GRANT SELECT ON sdtDB.* TO 'sdtreaduser'@'localhost';
# Grant permissions.
MariaDB> GRANT SELECT ON sdtDB.* TO 'sdtreaduser'@'localhost';

# Apply changes and exit.
MariaDB> flush privileges;
MariaDB> quit
# Apply changes and exit.
MariaDB> flush privileges;
MariaDB> quit
```

***NOTE:***
- For enhanced security, it's recommended to grant the software-discovery-tool user (sdtreaduser) only read (SELECT) permissions on the required database. This adheres to the principle of least privilege and minimizes the impact if the user credentials are compromised.
Expand All @@ -144,19 +167,29 @@ The `src/config/supported_distros.py` must now be updated to reflect the new jso
See `.env.example` and create a `.env` file in `/opt/software-discovery-tool/`, replacing the value of `DB_PASSWORD` with your own.

#### Run the script to populate the database, when prompted by the script for a user and password, use the root account and password you set above.

cd /opt/software-discovery-tool/bin/
./database_build.py

```bash
cd /opt/software-discovery-tool/bin/
./database_build.py
```
***NOTE:***
- If you encounter the following error:
```bash
pymysql.err.OperationalError: (1698, "Access denied for user 'root'@'localhost'")
```
Then give access to root user using:
```bash
mariadb -u root -p
MariaDB> ALTER USER 'root'@'localhost' IDENTIFIED VIA mysql_native_password USING PASSWORD('password'); # Replace the 'password' with the root password you set while installing mariadb.
```
### Step 7: Verify that the software-discovery-tool server is up and running
We now run the following commands to properly enable the config files of the software-discovery-tool server and then restart the apache server.

sudo a2ensite z-000-default.conf
systemctl reload apache2
sudo a2ensite sdt.conf
systemctl reload apache2
sudo apachectl restart

```bash
sudo a2ensite z-000-default.conf
systemctl reload apache2
sudo a2ensite sdt.conf
systemctl reload apache2
sudo apachectl restart
```
We can check if the server is up and running by going to following URL :

```http://server_ip_or_fully_qualified_domain_name:port_number/sdt``` <br />
Expand All @@ -165,9 +198,9 @@ We can check if the server is up and running by going to following URL :
```cd software-discovery-tool/src/tests``` <br />

If you run `pytest` as your logged user, it may give errors/warnings since you have given user `apache` ownership.

sudo -u apache pytest

```bash
sudo -u apache pytest
```
_**NOTE:**_

* By default the port_number will be 80
Expand Down Expand Up @@ -209,24 +242,28 @@ _**NOTE:**_
In case any of the parameters are updated, the server has to be restarted:

#### Start/Restart Apache service

sudo apachectl restart

```bash
sudo apachectl restart
```
### Step 9: Start React (frontend) server

#### Ensure Node.js and npm are installed

sudo apt install npm

```bash
Copy link
Contributor

@pleia2 pleia2 Oct 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

First question, did you have a problem with the npm package installed via apt? That's preferred over grabbing a static install script for maintainability and security, but if that wasn't working, it would be great to know what the problem was.

That said, running the following as-is installs npm as your regular user, so the apache user doesn't have access to run npm install later, I just get "command not found"

How did you get it so you could run npm install?

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
\. "$HOME/.nvm/nvm.sh"
nvm install 22
node -v # Should print "v22.20.0".
Copy link
Contributor

@pleia2 pleia2 Oct 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It gives me: v22.21.0

npm -v # Should print "10.9.3".
Copy link
Contributor

@pleia2 pleia2 Oct 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one gives me 10.9.4

```

#### Change to the react-frontend directory

cd react-frontend

```bash
cd react-frontend
```
#### Install the required npm packages

sudo npm i

```bash
npm install
Copy link
Contributor

@pleia2 pleia2 Oct 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As noted above, I tried a few things, but I didn't succeed in getting this running. There was either no access to the npm binary, or permissions issue (run as my user), or it wouldn't work (when I used the Ubuntu package).

Copy link
Contributor

@pleia2 pleia2 Oct 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good news! I was finally able to get this going using the package from Ubuntu (sudo apt install npm) and by running:

sudo -u apache npm install
sudo -u apache npm run start

And navigated to http://IP_ADDRESS:3000/

```
#### Setting up the Environment Variables

To configure the Flask server URL for your React application, follow these steps:
Expand All @@ -245,13 +282,14 @@ To configure the Flask server URL for your React application, follow these steps
- Open the newly created `.env` file and ensure it contains the following line:<br><br>

```plaintext
REACT_APP_API_URL='http://localhost:80/sdt'
REACT_APP_API_URL='http://server_ip_or_fully_qualified_domain_name:80/sdt'
```

3. **Use the Environment Variable:**

The `REACT_APP_API_URL` variable is now set and will be used by your React application to communicate with the Flask server running at the specified URL.

#### Start the react frontend application

sudo npm run start
```bash
npm run start
```