Merge pull request 'Add improved redame' (#18) from improve-readme into main

Reviewed-on: #18

.env.example

@@ -1,16 +1,16 @@
 DOMAIN=localhost
-DEMO=false
+DEMO=true
+# note that with DEBUG=true, logs are more verbose (include tracebacks)
+DEBUG=true
+ALLOWED_HOSTS=localhost,localhost:8000,127.0.0.1,
 
 STATIC_ROOT=/tmp/static/
 MEDIA_ROOT=/tmp/media/
-ALLOWED_HOSTS=localhost,localhost:8000,127.0.0.1,
-DOMAIN=localhost
-DEBUG=True
 EMAIL_HOST="mail.example.org"
 EMAIL_HOST_USER="fillme_noreply"
 EMAIL_HOST_PASSWORD="fillme_passwd"
 EMAIL_PORT=587
-EMAIL_USE_TLS=True
+EMAIL_USE_TLS=true
 EMAIL_BACKEND="django.core.mail.backends.smtp.EmailBackend"
 EMAIL_FILE_PATH="/tmp/app-messages"
 ENABLE_EMAIL=false

README.md

@@ -1,20 +1,123 @@
-# INSTALACIÓN:
+# Device Hub
 
-La instalación es muy estándar
+DeviceHub is an IT Asset Management System focused on reusing devices, created under the [eReuse.org](https://www.ereuse.org) project.
 
+## Overview
+
+DeviceHub aims to:
+
+- Provide a common IT Asset Management platform for donors, receivers, and IT professionals.
+- Automatically collect, analyze, and share device metadata while ensuring privacy and traceability.
+- Integrate with existing IT Asset Management Systems.
+- Operate in a decentralized manner.
+
+DeviceHub primarily works with three types of objects:
+
+1. **Devices**: Including computers, smartphones, and their components.
+2. **Events**: Actions performed on devices (e.g., Repair, Allocate).
+3. **Accounts**: Users who perform events on devices.
+
+## Installation
+
+Assuming a host with debian stable
+
+### Quickstart
+
+For a quick start with dummy data in localhost, DeviceHub can be run directly with docker. To do so, from the root of the project run:
+
+```bash
+./docker-reset.sh
 ```
+
+Note that everytime you perform the `docker-reset.sh` script, all data is lost.
+
+Also there is a demo running in http://demo.ereuse.org/. The token for accessing the instance will be always: `token=5018dd65-9abd-4a62-8896-80f34ac66150`, but the instance will be reset every day at 4 am.
+
+For production needs, review and change .env file properly
+
+## Running from baremetal
+
+### Prerequisites
+
+- Python 3.10
+- pip
+- virtualenv
+
+Specially when developing, is quite convenient to run DeviceHub from a virtual environment. To start with this deployment, create a virtual environment to isolate our project dependencies:
+
+```bash
 python -m venv env
-source env/bin/actevate
-python install -r requirements.txt
+source env/bin/activate
+pip install -r requirements.txt
 ```
 
-## IMPORTANT EXTERNAL DEPENDENCIES
+### System Dependencies
 
-Para arrancarlo es necesario tener el paquete `xapian-bindings` en tu ordenador. No se instala mediante `pip`, así que depende de cada [sistema operativo](https://xapian.org/download).
+#### Xapian
 
-Luego solo necesitas:
+Now, install the xapian dependencies (xapian library and python bindings)
 
+```bash
+sudo apt-get install python3-xapian libxapian-dev
 ```
-./manage.py migrate
-./manage.py runserver
+
+Allow the virtual environment to use system-installed packages:
+
+```bash
+export PYTHONPATH="${PYTHONPATH}:/usr/lib/python3/dist-packages"
 ```
+
+#### Environment Variables
+
+Now, configure the environment variables. For this, we will expand a `.env` file. You can use the following content as an example:
+
+```source
+STATIC_ROOT=/tmp/static/
+MEDIA_ROOT=/tmp/media/
+ALLOWED_HOSTS=localhost,localhost:8000,127.0.0.1,
+DOMAIN=localhost
+DEBUG=True
+```
+
+Now, expand the environment variables:
+
+```bash
+source .env
+```
+
+### Migrations
+
+Now, apply migrations
+
+```bash
+python manage.py makemigrations
+python manage.py migrate
+```
+
+Also, we can add some dummy data into the database to play along:
+
+```bash
+python manage.py add_institution Pangea
+python manage.py add_user Pangea user@example.org 1234
+python manage.py up_snapshots example/snapshots/ user@example.org
+```
+
+### Run DeviceHub
+
+Finally, we can run the DeviceHub service by running:
+
+```bash
+python manage.py runserver
+```
+
+### Clean up
+
+To clean up the deployment and start fresh, just delete Django's database:
+
+```bash
+rm db/*
+```
+
+## License
+
+DeviceHub is released under the [GNU Affero General Public License v3.0](LICENSE).

device/templates/details.html

@@ -55,8 +55,7 @@
       <div class="col-lg-3 col-md-4 label ">{% trans "Type" %}</div>
       <div class="col-lg-9 col-md-8">{{ object.type }}</div>
     </div>
-
-    {% if object.is_websnapshot %}
+    {% if object.is_websnapshot and object.last_user_evidence %}
     {% for k, v in object.last_user_evidence %}
     <div class="row">
       <div class="col-lg-3 col-md-4 label">{{ k }}</div>

docker-reset.sh

@@ -14,6 +14,11 @@ main() {
         if [ "${DETACH:-}" ]; then
                 detach_arg='-d'
         fi
+
+        if [ ! -f .env ]; then
+                cp -v .env.example .env
+                echo "WARNING: .env was not there, .env.example was copied, this only happens once"
+        fi
         # remove old database
         sudo rm -vfr ./db/*
         docker compose down -v

evidence/forms.py

@@ -35,10 +35,14 @@ class UploadForm(forms.Form):
                 ).first()
 
                 if exist_annotation:
-                    raise ValidationError("error: {} exist".format(file_name))
+                    raise ValidationError("Error: {} already exists".format(file_name))
 
-            except Exception:
-                raise ValidationError("error in: {}".format(file_name))
+            except json.JSONDecodeError:
+                raise ValidationError("Error in parsing JSON: '{}'. Check for file integrity.".format(file_name))
+            except ValidationError as e:
+                raise e
+            except Exception as e:
+                raise ValidationError("Oops! Something went wrong in '{}': {}".format(file_name, str(e)))
 
             self.evidences.append((file_name, file_json))
 

evidence/management/commands/up_snapshots.py

@@ -1,12 +1,18 @@
-
 import os
 import json
+import logging
 
 from django.core.management.base import BaseCommand
 from django.contrib.auth import get_user_model
+from django.conf import settings
+
+from utils.save_snapshots import move_json, save_in_disk
 from evidence.parse import Build
 
 
+logger = logging.getLogger('django')
+
+
 User = get_user_model()
 
 
@@ -31,9 +37,11 @@ class Command(BaseCommand):
 
         elif os.path.isdir(path):
             self.read_directory(path)
+        else:
+            raise ValueError(f"The path {path} is neither a file nor a directory")
 
         self.parsing()
-            
+
     def read_directory(self, directory):
         for filename in os.listdir(directory):
             filepath = os.path.join(directory, filename)
@@ -41,10 +49,27 @@ class Command(BaseCommand):
                 self.open(filepath)
 
     def open(self, filepath):
-        with open(filepath, 'r') as file:
-            content = json.loads(file.read())        
-            self.snapshots.append(content)
-        
+        try:
+            with open(filepath, 'r') as file:
+                content = json.loads(file.read())
+                path_name = save_in_disk(content, self.user.institution.name)
+
+                self.snapshots.append((content, path_name))
+        except json.JSONDecodeError as e:
+            raise e
+        #or we cath'em all
+        except Exception:
+            raise Exception(f"Oops! Something went wrong there")
+
+
     def parsing(self):
-        for s in self.snapshots:
-            self.devices.append(Build(s, self.user))
+        for s, p in self.snapshots:
+            try:
+                self.devices.append(Build(s, self.user))
+                move_json(p, self.user.institution.name)
+            except Exception as err:
+                if settings.DEBUG:
+                    logger.exception("%s", err)
+                snapshot_id = s.get("uuid", "")
+                txt = "It is not possible to parse snapshot: %s"
+                logger.error(txt, snapshot_id)

evidence/parse.py

@@ -5,23 +5,15 @@ import logging
 from dmidecode import DMIParse
 from json_repair import repair_json
 
+from evidence.parse_details import get_lshw_child
 from evidence.models import Annotation
 from evidence.xapian import index
 from utils.constants import CHASSIS_DH
 
 
-logger = logging.getLogger('django')
-
-
-def get_network_cards(child, nets):
-    if child['id'] == 'network' and "PCI:" in child.get("businfo"):
-        nets.append(child)
-    if child.get('children'):
-        [get_network_cards(x, nets) for x in child['children']]
-
+logger = logging.getLogger(__name__)
 
 def get_mac(lshw):
-    nets = []
     try:
         if type(lshw) is dict:
             hw = lshw
@@ -30,19 +22,17 @@ def get_mac(lshw):
     except json.decoder.JSONDecodeError:
         hw = json.loads(repair_json(lshw))
 
-    try:
-        get_network_cards(hw, nets)
-    except Exception as ss:
-        print("WARNING!! {}".format(ss))
-        return
+    networks = []
+    get_lshw_child(hw, networks, 'network')
 
-    nets_sorted = sorted(nets, key=lambda x: x['businfo'])
+    nets_sorted = sorted(networks, key=lambda x: x['businfo'])
     # This funcion get the network card integrated in motherboard
     # integrate = [x for x in nets if "pci@0000:00:" in x.get('businfo', '')]
 
     if nets_sorted:
-        return nets_sorted[0]['serial']
-
+        mac = nets_sorted[0]['serial']
+        logger.debug("The snapshot has the following MAC: %s" , mac)
+        return mac
 
 class Build:
     def __init__(self, evidence_json, user, check=False):