From 05f7444ecd2e3405b0e595042166ec5f8a3395ab Mon Sep 17 00:00:00 2001
From: diogo464 <diogo464@d464.sh>
Date: Wed, 28 May 2025 20:46:55 +0100
Subject: init

---
 README.md | 184 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 184 insertions(+)
 create mode 100644 README.md

(limited to 'README.md')

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1467530
--- /dev/null
+++ b/README.md
@@ -0,0 +1,184 @@
+# Bonsai Web
+
+A simple web interface for the Bonsai network latency graph generator.
+
+## Features
+
+- Clean, modern UI using Pico CSS
+- YAML configuration input
+- Real-time file generation
+- File viewing and downloading capabilities
+- Containerized deployment support
+
+## Local Development
+
+### Prerequisites
+
+- Python 3.9+
+- Flask
+
+### Installation
+
+1. Clone this repository
+2. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+### Running Locally
+
+```bash
+python app.py
+```
+
+The application will be available at `http://localhost:5000`
+
+### Environment Configuration
+
+The application behavior can be controlled using the `BONSAI_TEST_MODE` environment variable:
+
+- **Test Mode** (default for local development): `BONSAI_TEST_MODE=true`
+  - If Bonsai fails or is not available, dummy files are generated for testing
+  - Useful for development and testing the web interface
+  
+- **Production Mode**: `BONSAI_TEST_MODE=false`
+  - If Bonsai fails, proper error messages are returned to the user
+  - No dummy files are generated
+
+```bash
+# Run in production mode
+BONSAI_TEST_MODE=false python app.py
+
+# Run in test mode (default)
+BONSAI_TEST_MODE=true python app.py
+# or simply
+python app.py
+```
+
+### Development Mode
+
+For development, the application includes fallback dummy data generation when `BONSAI_TEST_MODE=true` and the actual Bonsai tool is not available. This allows you to test the web interface without having the full Bonsai installation.
+
+**Error Handling**: When Bonsai fails in production mode, detailed error messages are displayed to the user in red text, including:
+- Execution failures with return codes and stderr output
+- Timeout errors (30-second limit)
+- Missing Bonsai installation errors
+
+## Container Deployment
+
+### Building the Container
+
+#### Local Build (for testing)
+```bash
+./build.sh
+```
+
+#### Production Build and Push
+```bash
+PUSH=1 ./build.sh
+```
+
+The build script will:
+- Always build the container image with appropriate tags
+- Only push to `git.d464.sh/diogo464/bonsai-web` when `PUSH=1` is set
+- Use git tags for versioning (or 'latest' if no tag)
+- Check registry authentication only when pushing
+
+#### Manual Build Commands
+
+```bash
+# Local build
+podman build -t bonsai-web -f Containerfile .
+
+# Production build and push
+podman build -t git.d464.sh/diogo464/bonsai-web:latest -f Containerfile .
+podman push git.d464.sh/diogo464/bonsai-web:latest
+```
+
+### Running the Container
+
+#### From Local Build
+```bash
+podman run -p 5000:5000 bonsai-web:local
+```
+
+#### From Registry
+```bash
+podman run -p 5000:5000 git.d464.sh/diogo464/bonsai-web:latest
+```
+
+### Registry Authentication
+
+Before pushing to the registry, authenticate with:
+```bash
+podman login git.d464.sh
+```
+
+### Bonsai Integration
+
+To integrate with the actual Bonsai tool, modify the `Containerfile` in the "BONSAI SETUP SECTION" to:
+
+1. Clone or copy the Bonsai source code to `/usr/src/bonsai`
+2. Install Bonsai's dependencies
+3. Ensure the Bonsai tool is properly configured
+
+Example:
+```dockerfile
+# In the BONSAI SETUP SECTION of Containerfile
+RUN git clone https://github.com/your-org/bonsai.git /usr/src/bonsai
+WORKDIR /usr/src/bonsai
+RUN pip install -r requirements.txt
+WORKDIR /app
+```
+
+## Usage
+
+1. Open the web application in your browser
+2. Enter your network configuration in YAML format in the text area
+3. Click "Generate Network Files"
+4. View or download the generated `edges.csv` and `nodes.csv` files
+
+### Example Configuration
+
+```yaml
+network:
+  nodes: 10
+  density: 0.3
+  latency_range: [1, 100]
+```
+
+## API
+
+### POST /
+
+Generates network files from a YAML configuration.
+
+**Request Body:**
+```json
+{
+  "config": "network:\n  nodes: 10\n  density: 0.3"
+}
+```
+
+**Response:**
+```json
+{
+  "edges.csv": "source,target,weight\nnode1,node2,0.5\n...",
+  "nodes.csv": "id,label,x,y\nnode1,Node 1,0,0\n..."
+}
+```
+
+## Project Structure
+
+```
+.
+├── app.py              # Flask backend
+├── index.html          # Main web page
+├── script.js           # Client-side JavaScript
+├── logo.png            # Bonsai logo
+├── requirements.txt    # Python dependencies
+├── Containerfile       # Container build instructions
+├── build.sh            # Container build script
+├── .gitignore          # Git ignore patterns
+└── README.md          # This file
+``` 
\ No newline at end of file
-- 
cgit