Merge pull request #54 from Boavizta/dev

Update Boagent to 0.1.0

.dockerignore

@@ -1 +1,2 @@
 .git
+venv

.github/workflows/greenhack22.yml

@@ -11,17 +11,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Login to GitHub Container Registry
-        uses: docker/login-action@v1
+        uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Setup Python 3
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: '3.9'
 

.github/workflows/release.yml

@@ -10,22 +10,25 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Login to GitHub Container Registry
-        uses: docker/login-action@v1
+        uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Setup Python 3
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: '3.9'
 
+      - name: Install poetry
+        run: python -m pip install --upgrade poetry wheel
+
       - name: Build  docker image
-        run: docker build . --tag ghcr.io/boavizta/boagent:$(python3 setup.py --version)
+        run: docker build . --tag ghcr.io/boavizta/boagent:$(poetry version -s)
 
       - name: Push docker image
-        run: docker push ghcr.io/boavizta/boagent:$(python3 setup.py --version)
+        run: docker push ghcr.io/boavizta/boagent:$(poetry version -s)

.github/workflows/test.yml

@@ -0,0 +1,40 @@
+name: Execute tests
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+    paths:
+      - "boagent/**"
+      - "tests/**"
+      - "poetry.lock"
+      - "pyproject.toml"
+  pull_request:
+    branches:
+      - main
+      - dev
+    paths:
+      - "boagent/**"
+      - "tests/**"
+      - "poetry.lock"
+      - "pyproject.toml"
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        version: ["3.10", "3.11"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Python setup
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.version }}
+      - name: Poetry setup
+        run : python3 -m pip install --upgrade poetry wheel
+      - name: Install dependencies
+        run: poetry install
+      - name: Execute tests
+        run: poetry run python3 -m pytest

.gitignore

@@ -137,4 +137,6 @@ dmypy.json
 .idea/
 .vscode/
 
-*.json
+*.db
+*.svg
+*.csv

.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v2.3.0
+    hooks:
+    -   id: check-yaml
+    -   id: end-of-file-fixer
+    -   id: trailing-whitespace
+-   repo: https://github.com/psf/black
+    rev: 22.10.0
+    hooks:
+    -   id: black
+-   repo: https://github.com/PyCQA/flake8
+    rev: 7.0.0
+    hooks:
+    - id: flake8
+      entry: flake8 --ignore=E501,W503 --per-file-ignores='__init__.py:F401'

Dockerfile

@@ -1,25 +1,21 @@
 FROM python:3.10-slim
 
-LABEL org.opencontainers.image.authors="bpetit@hubblo.org"
-
-RUN apt update && apt install gcc g++ -y
-
-RUN apt-get install -y cron sqlite3
-
-RUN useradd -ms /bin/bash boagent
-
-#USER boagent
+LABEL org.opencontainers.image.authors="open-source@boavizta.org"
+LABEL org.opencontainers.image.description="Docker image for Boagent, a local API & environmental impact monitoring tool."
+LABEL org.opencontainers.image.licenses=Apache-2.0
 
 WORKDIR /home/boagent
 
-COPY requirements.txt requirements.txt
+RUN python3 -m pip install --upgrade poetry
+
+RUN apt update && apt install lshw nvme-cli -y
 
-RUN pip3 install -r requirements.txt
+COPY pyproject.toml .
 
-ENV PATH $PATH:/home/boagent/.local/bin
+RUN poetry install
 
 COPY . .
 
 EXPOSE 8000
 
-ENTRYPOINT [ "/bin/bash", "-c", "cd boagent/api && uvicorn api:app --host 0.0.0.0" ]
+ENTRYPOINT ["poetry", "run", "uvicorn", "--reload", "boagent.api.api:app", "--host", "0.0.0.0"]

README.md

@@ -11,51 +11,73 @@ _If no parameters are passed to the API to isolate the application, then the imp
 
 ## How to use
 
-This is an API, you could use either your browser, curl, or call it directly from an application (which is the main usecase).
+This is an API, you could use either your browser, cURL, or call it directly from an application (which is the main usecase).
 
 Once the API is running, a Swagger interface is available on [localhost:8000/docs](http://localhost:8000/docs).
 
+
 ### Run natively
 
+Boagent will not be able to return proper responses from its endpoints without root privileges in order to fetch hardware data.
+It also needs information from BoaviztAPI and Scaphandre, see the [setup informations](#Setup).
+
 To run it :
 
+Without `poetry`
+
 ```
-cd boagent/
+apt update && apt install lshw nvme-cli -y
 pip3 install -r requirements.txt
-cd api/
+cd boagent/api/
 uvicorn api:app --reload
 ```
 
-The app can run without root privileges, but you won't get full data about the RAM and get some warnings.
-Run as root to have the best evaluation possible.
+With `poetry`
+
+```
+apt update && apt install lshw nvme-cli -y
+poetry install --only main
+poetry run uvicorn --reload boagent.api.api:app
+```
 
 ### Run in a docker container
 
 You could pull the [image](https://github.com/Boavizta/boagent/pkgs/container/boagent) with `docker pull ghcr.io/boavizta/boagent:latest`.
 
 ### Run in docker-compose (with all the requirements)
 
-To get started you need docker and docker-compose installed on your machine. On a debian or ubuntu machine, run :
+To get started you need docker and docker-compose installed on your machine. On a Debian or Ubuntu environment, run :
 
     # apt update && apt install -y docker.io docker-compose
 
-To get the full setup easily, you could run the stack in docker-compose with `docker-compose up -d`. `docker-compose.yml`, at the root of the project will build a docker image from the source for boagent, and setup a container for [Scaphandre](#Scaphandre) and another for the [BoaviztAPI](#BoaviztAPI), allowing you to get the full evaluation easily on a physical machine.
+To get the full setup easily, you could run the stack in docker-compose with `docker-compose up -d`. `docker-compose.yml`, at the root of the project will build a Docker image from the source for Boagent, and setup a container for [Scaphandre](#Scaphandre) and another for the [BoaviztAPI](#BoaviztAPI), allowing you to get the full evaluation easily on a physical machine.
 
 Please see [Configuration](#Configuration) for the environment variables you can tweak in the Boagent container.
 
-## Setup required
+### Use `hardware_cli`
+
+To have an example of the retrieved hardware information by Boagent, you can run `sudo ./hardware_cli.py`.
+At the moment, it will output the formatted data for CPU, RAM and storage devices used by Boagent when sending a request to BoaviztAPI.
+`sudo ./hardware_cli.py --output-file <file>` can send the formatted output to a file.
+
+## Setup
+
+## Linux
+
+Boagent parses output from `lshw` (a tool listing hardware components and characteristics) and `nvme-cli` (a tool listing information on SSD storage
+devices available through NVME interfaces). To get all actually parsed information (and for future developments), Boagent needs those two programs and toexecute them with root privileges.
 
 ### BoaviztAPI
 
 You need either to use an existing BoaviztAPI endpoint, or to build the BoaviztAPI container image, then run the container locally on port 5000.
 
 Depending or your setup, specify the endpoint to be used with the environment variable `BOAVIZTAPI_ENDPOINT`, see [Configuration](#Configuration).
 
-Ensure that the version of BoaviztAPI SDK installed (see `requirements.txt`) is the same as the version of the API running the endpoint you use.
+Ensure that the version of BoaviztAPI SDK installed (see `requirements.txt` or `pyproject.toml`) is the same as the version of the API running the endpoint you use.
 
 ### Scaphandre
 
-To get power consumption metrics, you need [Scaphandre](https://github.com/hubblo-org/scaphandre) runnig in the background, with the json exporter. This will write power metrics to a file, that Boagent will read :
+To get power consumption metrics, you need [Scaphandre](https://github.com/hubblo-org/scaphandre) running in the background, with the JSON exporter. This will write power metrics to a file, that Boagent will read :
 
 ```
 scaphandre json -s 5 -f power_data.json
@@ -65,11 +87,11 @@ scaphandre json -s 5 -f power_data.json
 
 Boagent can be configured with the following variables :
 
-- `DEFAULT_LIFETIME`: machines lifetime used to compute the scope 3 / manufacturing, transport, end of life impacts
-- `HARDWARE_FILE_PATH`: path to the file containing the hardware list (output from hardware.py)
-- `POWER_FILE_PATH`: path to the file containing power mearsurements (output from [Scaphandre](https://github.com/hubblo-org/scaphandre) with JSON exporter)
-- `HARDWARE_CLI`: path to the executable file to collect hardware information (hardware.py from this project)
-- `BOAVIZTAPI_ENDPOINT`: http endpoint to the BoaviztAPI, in the form `http://myendpoint.com:PORTNUMBER`
+- `DEFAULT_LIFETIME`: machines lifetime used to compute the scope 3 / manufacturing, transport, end-of-life impacts
+- `HARDWARE_FILE_PATH`: path to the file containing the hardware list (output from `lshw.py`)
+- `POWER_FILE_PATH`: path to the file containing power measurements (output from [Scaphandre](https://github.com/hubblo-org/scaphandre) with JSON exporter)
+- `HARDWARE_CLI`: path to the executable file to collect hardware information (`lshw.py` from this project)
+- `BOAVIZTAPI_ENDPOINT`: HTTP endpoint to the BoaviztAPI, in the form `http://myendpoint.com:PORTNUMBER`
 
 You can set those variables in the following order (as interpreted by the tool):
 
@@ -79,6 +101,20 @@ You can set those variables in the following order (as interpreted by the tool):
 
 You can check the configuration applied by querying the `/info` route.
 
+## How it works
+
+Currently, Boagent only works for Linux systems.
+
+Boagent exposes multiple API endpoints, most notably `/query` and `/metrics`. Both will query an instance of [BoaviztAPI](https://doc.api.boavizta.org/) in order to give the environmental impacts
+of the received hardware data. `/query` will return a response in JSON format, and `/metrics` will return a response parsable by a Prometheus instance. If needed, both those
+endpoints can return data from [Scaphandre](https://github.com/hubblo-org/scaphandre/) and give the energy consumption of components from the queried hardware.
+
+Presently, Boagent gets hardware data through a parsing of the output of `lshw`, a common utility available for Linux distributions that lists a lot of information of all
+hardware components on a running computer. The code for this `Lshw` class is an adaptation of [netbox-agent](https://github.com/Solvik/netbox-agent)'s implementation.
+`lshw`, to get all proper data needed by BoaviztAPI, needs to be executed as a privileged user with `sudo`. Boagent, executed with the available `docker-compose` file,
+will run as privileged and will be able to receive the needed hardware data. At the moment, only data for the CPU, RAM and storage (either HDD or SSD) are parsed and sent to BoaviztAPI
+in order to calculate impacts.
+
 ## Deeper explanations
 
 ### Environmental metrics

boagent/__init__.py

@@ -4,6 +4,6 @@
 Monitoring agent/framework for evaluating the environmental impacts of a machine and its applications, including several to all steps of the life cycle of the machine and service, plus multiple criterias of impacts (not just CO2eq metrics / Global Warming Potential). Part of the efforts of https://boavizta.org/en and https://sdialliance.org/.
 """
 
-__version__ = "0.0.8"
-__author__ = 'Benoit Petit <bpetit@hubblo.org>'
-__credits__ = 'Boavizta contributors'
+__version__ = "0.1.0"
+__author__ = "Boavizta <open-source@boavizta.org>"
+__credits__ = "Boavizta contributors"