Improve handling of missing HOST_PWD variable and other fixes.

- Handle missing HOST_PWD gracefully
- Use gunicorn in favor of werkzeug
- Reduce Docker build context
- Improve README.md and overall usability

.dockerignore

@@ -11,10 +11,12 @@
 aws
 binaries
 browser-repos
+config
 database
 Dockerfile
 docker-compose.yaml
 drivers
+experiments
 extensions
 logs
 support

.env

@@ -0,0 +1,8 @@
+# DO NOT CHANGE OR REMOVE THIS FILE!
+# If you wish to modify a variable, do so by assigning it before the command:
+# For example, `BUGHOG_VERSION=dev docker compose up` to pull the development version.
+
+BUGHOG_VERSION=latest
+BUGHOG_WEB_VERSION=latest
+
+COMPOSE_PROFILES=prod

.gitignore

@@ -1,6 +1,5 @@
 test/resources/repositories
 browser/binaries/
-config/
 database/data/
 !**/.gitkeep
 **/node_modules
@@ -116,7 +115,7 @@ celerybeat.pid
 *.sage.py
 
 # Environments
-.env
+config/.env
 .venv
 env/
 venv/

README.md

@@ -23,83 +23,85 @@ This framework has been developed as part of the _"A Bug's Life: Analyzing the L
     width="100"/>
 
 
-## Usage
-
-### Prerequisites
-- Docker (tested with version 24.0.1)
+## Installation
 
-### Installing
-BugHog can be installed by following the steps below:
+BugHog is compatible with UNIX systems running Docker, including WSL on Windows.
+Follow these steps to get started:
 
-1. Clone this repository:
+1. **Clone this repository:**
 
     ```bash
     git clone https://github.com/DistriNet/BugHog
     cd BugHog
     ```
 
-2. Obtain images:
+2. **Obtain images:**
 
     You will need at least 5 GB of disk space.
+    There are two options available to obtain the BugHog images, and you can switch between them by executing the appropriate command.
 
-    *Option A: Pulling (fastest)*
+    ***Option A:** Pulling (fastest)*
 
     Use the following command to pull the necessary Docker images:
     ```bash
     docker compose pull core worker web
     ```
 
-    *Option B: Building*
+    > :bulb: If you prefer to use a version other than the latest, simply modify the `BUGHOG_VERSION` and / or `BUGHOG_WEB_VERSION` variables accordingly.
+
+    ***Option B:** Building*
 
-    If you want to modify the source code, use the following commands to build the necessary Docker images.
-    Run this script again if you make changes to the source code.
+    Use the following commands to build the Docker images yourself, for instance after you made changes to the source code:
     ```bash
     docker compose build core worker web
     ```
 
     > :bulb: For reference, building takes about 4 minutes on a machine with 8 CPU cores and 8 GB of RAM.
 
-### Starting
-After pulling or building the images, start BugHog with the following command.
-If you switch between pulled and built images, make sure to execute the appropriate commands mentioned above before starting.
+
+## Usage
+
+Launch BugHog using the following command:
 ```bash
-docker compose up core web
+docker compose up
 ```
 
+> :warning: If you use `sudo` with this command, the `PWD` environment variable won't be passed to the BugHog containers, which is necessary for dynamically starting worker containers.
+> To avoid this, explicitly pass on this variable: `sudo PWD=$PWD docker compose up`.
+
 Open your web browser and navigate to [http://localhost:5000](http://localhost:5000) to access the graphical interface.
-If you started BugHog on a remote server, replace localhost with its IP address.
+BugHog is started on a remote server, substitute 'localhost' with its IP address.
+
+BugHog can be stopped through:
+```bash
+docker compose down
+```
 
 > :warning: BugHog's own MongoDB instance will persist data within the [database](database) folder.
 > Be sure to back-up accordingly, or use your own MongoDB instance as explained below.
 
-#### Optional: Use your own MongoDB instance
 
-By default, BugHog uses a MongoDB container.
-you might want to prefer all data to be stored on your own MongoDB instance.
+### Optional: Use your own MongoDB instance
+
+By default, BugHog uses a MongoDB container to store data.
 If you prefer storing data in your own MongoDB instance, follow these steps:
 
-1. Create a `.env` file from `.env.example` (both in the [config](config) folder) and fill in the missing values.
+1. Create a `.env` file from `.env.example` (both in the [config](config) folder) and fill in the missing database values.
 
 2. (Re)start BugHog.
 
-### Stopping
-To stop BugHog, run the following command:
-
-```bash
-docker compose down
-```
 
-### Adding Your Own Experiments
+### Adding your new experiments
 
 Instructions to add your own custom experiments to the server can be found [here](https://github.com/DistriNet/BugHog-web/blob/main/experiments/README.md).
 Be sure to restart the BugHog framework when you add a new experiment:
 
 ```bash
 docker compose down
-docker compose up core web
+docker compose up
 ```
 
-### Development
+## Development
 
 For extending or debugging the Vue UI, the most convenient approach is to launch an interactive Node environment.
 The UI can be visited at [http://localhost:5173](http://localhost:5173).
@@ -108,9 +110,18 @@ The UI can be visited at [http://localhost:5173](http://localhost:5173).
 docker compose up node_dev
 ```
 
-For debugging the core application, consider using the VS Code dev container for an effortless debugging experience.
+For debugging the core application, consider using the VS Code dev container.
 You can utilize the configuration in [.devcontainer](.devcontainer) for this.
 
+
 ## Additional help
 
 Don't hesitate to open a [GitHub issue](https://github.com/DistriNet/BugHog/issues/new) if you come across a bug, want to suggest a feature, or have any questions!
+
+
+## Troubleshooting
+
+### WSL on Windows
+
+- Ensure you clone the BugHog project to the WSL file system instead of the Windows file system, and launch it from there.
+Virtualization between these file systems can cause complications with file management.

bci/configuration.py

@@ -27,6 +27,15 @@ def get_browser_config_class(browser: str):
             case _:
                 raise ValueError(f'Invalid browser \'{browser}\'')
 
+    @staticmethod
+    def check_required_env_parameters() -> bool:
+        if (host_pwd:=os.getenv('HOST_PWD')) in ['', None]:
+            logger.fatal('The "HOST_PWD" variable is not set. If you\'re using sudo, you might have to pass it explicitly, for example "sudo HOST_PWD=$PWD docker compose up"')
+            return False
+        else:
+            logger.debug(f'HOST_PWD={host_pwd}')
+            return True
+
     @staticmethod
     def initialize_folders():
         for browser in ['chromium', 'firefox']:

bci/main.py

@@ -21,7 +21,8 @@ class Main:
     def initialize():
         Main.loggers = Loggers()
         Main.loggers.configure_loggers()
-        Main.master = Master()
+        if Global.check_required_env_parameters():
+            Main.master = Master()
 
     @staticmethod
     def is_ready() -> bool:

bci/ui/app.py

@@ -3,17 +3,18 @@
 import os
 
 from flask import Flask, send_from_directory
-from flask_socketio import SocketIO
 
 from bci.ui.blueprints.api import api
 
 
 app = Flask(__name__)
-app.register_blueprint(api)
-socketio = SocketIO(app)
 
-# We don't store anything sensitive in the session, so we can use a simple secret key
-app.secret_key = 'secret_key'
+
+def create_app():
+    app.register_blueprint(api)
+    # We don't store anything sensitive in the session, so we can use a simple secret key
+    app.secret_key = 'secret_key'
+    return app
 
 
 @app.route('/', methods=['GET'])
@@ -25,13 +26,3 @@ def index():
 def serve_static_files(file_path):
     path = os.path.join('dist', file_path)
     return send_from_directory('frontend', path)
-
-
-if __name__ == "__main__":
-    # Configure flask logger
-    filer_handler = logging.handlers.RotatingFileHandler("/app/logs/flask.log", mode='a', backupCount=2)
-    filer_handler.setLevel(logging.DEBUG)
-    logging.getLogger('werkzeug').addHandler(filer_handler)
-
-    # Debug is set to false because it would otherwise auto-reload (run the program twice)
-    socketio.run(app, debug=False, host="0.0.0.0", allow_unsafe_werkzeug=True)

bci/ui/blueprints/api.py

@@ -32,7 +32,10 @@ def check_readiness():
     if not bci_api.is_ready():
         return {
             'status': 'NOK',
-            'msg': 'BugHog is not ready.'
+            'msg': 'BugHog is not ready',
+            'info': {
+                'log': bci_api.get_logs(),
+            }
         }
 
 

bci/ui/frontend/src/App.vue

@@ -68,6 +68,7 @@ export default {
       target_mech_id_input: null,
       target_mech_id: null,
       should_refresh_plot: false,
+      fatal_error: null,
     }
   },
   computed: {
@@ -94,8 +95,11 @@ export default {
         return "p {color: black;}";
       }
     },
-    "database_message": function () {
-      if (this.info.database.connected) {
+    "banner_message": function () {
+      if (this.fatal_error) {
+        return `A fatal error has occurred! Please, check the logs below...`
+      }
+      else if (this.info.database.connected) {
         return `Connected to MongoDB at ${this.info.database.host}`;
       } else {
         return `Connecting to database...`;
@@ -186,13 +190,14 @@ export default {
       const path = `http://${location.hostname}:5000/api/info/`;
       axios.get(path)
         .then((res) => {
-          if (res.data.status == "OK") {
+          if (res.data.status === "OK") {
             if (log_section.scrollHeight - log_section.scrollTop - log_section.clientHeight < 1) {
               this.info = res.data.info;
               log_section.scrollTo({ "top": log_section.scrollHeight, "behavior": "auto" });
-            } else {
-              this.info = res.data.info;
             }
+          } else {
+            this.info.log = res.data.info.log;
+            this.fatal_error = true;
           }
         })
         .catch((error) => {
@@ -362,7 +367,7 @@ export default {
     </div>
 
     <!-- <p>[FRAMEWORK NAME + LOGO]</p> -->
-    <p>{{ database_message }}</p>
+    <p :class="{ '!font-bold !text-red-600' : fatal_error }">{{ banner_message }}</p>
 
     <label class="inline-flex items-center cursor-pointer">
       <input id="darkmode_toggle" type="checkbox" class="sr-only peer" @click="toggle_darkmode($event)"

config/.env.example

@@ -1,3 +1,6 @@
+# Copy this file to config/.env en change it there if you would like to change your configuration.
+
+# Database parameters
 BCI_MONGO_HOST=
 BCI_MONGO_USERNAME=
 BCI_MONGO_DATABASE=