From 850a56b826062052bb0768e8d791d5243ee14c61 Mon Sep 17 00:00:00 2001 From: Parth Date: Thu, 19 Feb 2026 23:59:41 +0530 Subject: [PATCH] Add cross-platform development setup documentation - Add macOS/Linux/Windows from-source setup guide - Document solver installation and PATH configuration - Document requirements.txt encoding behavior - Document DataStorage permission considerations - Register page in Getting Started toctree - Link documentation from README Refs #12 --- README.md | 14 ++ docs/source/getting-started/dev-setup.rst | 149 ++++++++++++++++++++++ docs/source/index.rst | 2 + 3 files changed, 165 insertions(+) create mode 100644 docs/source/getting-started/dev-setup.rst diff --git a/README.md b/README.md index 001bb8b9..fe3f91be 100644 --- a/README.md +++ b/README.md @@ -17,3 +17,17 @@ This repository contains the user interface for the Open Source Energy Modelling For troubleshooting model-related issues and discussions, please visit the [Energy Modelling Community Discussion Forum](https://forum.u4ria.org/). If you encounter bugs or have new feature ideas, please submit them to the repository's issue tracker. We encourage contributions and discussions to further develop MUIO. + +## Development (Run from Source) + +For macOS, Linux, or Windows source-based development setup instructions, see: + +`docs/source/getting-started/dev-setup.rst` + +This guide covers: + +- Installing GLPK and CBC solvers +- Creating a Python virtual environment +- Installing dependencies +- Running the Flask development server +- Troubleshooting solver detection and permissions diff --git a/docs/source/getting-started/dev-setup.rst b/docs/source/getting-started/dev-setup.rst new file mode 100644 index 00000000..9601fe33 --- /dev/null +++ b/docs/source/getting-started/dev-setup.rst @@ -0,0 +1,149 @@ +Development Setup (macOS / Linux / Windows from Source) +======================================================= + +This section describes how to run MUIO from source for development purposes. +These steps are intended for contributors and research teams working on macOS, +Linux, or Windows without using the packaged `.exe`. + +Prerequisites +------------- + +- Python 3.9+ +- Git +- GLPK and CBC solvers installed on the system +- pip (Python package installer) + +macOS (Apple Silicon or Intel) +------------------------------ + +1. Install solvers using Homebrew: + + .. code-block:: bash + + brew install glpk + brew install coin-or-tools/coinor/cbc + + Note: `cbc` is keg-only. Add it to your PATH: + + .. code-block:: bash + + echo 'export PATH="/opt/homebrew/opt/cbc/bin:$PATH"' >> ~/.zshrc + source ~/.zshrc + +2. Create a virtual environment: + + .. code-block:: bash + + python3 -m venv venv + source venv/bin/activate + +3. Install dependencies: + + .. code-block:: bash + + pip install --upgrade pip + pip install -r requirements.txt + +4. Start the application: + + .. code-block:: bash + + python API/app.py + +5. Open in browser: + + http://127.0.0.1:5002 + +Linux (Ubuntu/Debian) +--------------------- + +1. Install solvers: + + .. code-block:: bash + + sudo apt update + sudo apt install glpk-utils coinor-cbc + +2. Create virtual environment: + + .. code-block:: bash + + python3 -m venv venv + source venv/bin/activate + +3. Install dependencies: + + .. code-block:: bash + + pip install --upgrade pip + pip install -r requirements.txt + +4. Run the server: + + .. code-block:: bash + + python API/app.py + +5. Open in browser: + + http://127.0.0.1:5002 + +Windows (From Source) +--------------------- + +The recommended approach for Windows users is to use the packaged `.exe`. +However, running from source is also possible: + +1. Install Python 3.9+ +2. Install GLPK and CBC and ensure they are available on PATH. +3. Create virtual environment: + + .. code-block:: bash + + python -m venv venv + venv\Scripts\activate + +4. Install dependencies: + + .. code-block:: bash + + pip install --upgrade pip + pip install -r requirements.txt + +5. Run: + + .. code-block:: bash + + python API/app.py + +Important Notes +--------------- + +Solver Detection +~~~~~~~~~~~~~~~~ + +On macOS/Linux, MUIO automatically detects `glpsol` and `cbc` +from the system PATH. Environment variable overrides are also supported: + +- ``MUIO_GLPK_PATH`` +- ``MUIO_CBC_PATH`` + +requirements.txt Encoding +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``requirements.txt`` file is encoded in UTF-16LE. +`pip install -r requirements.txt` handles this correctly. +Some external tools may require converting the file to UTF-8. + +File Permissions (macOS/Linux) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`Config.py` contains: + +.. code-block:: python + + os.chmod(DATA_STORAGE, 0o777) + +This runs at import time. If permission errors occur, +ensure the ``WebAPP/DataStorage`` directory exists and +has appropriate write permissions. diff --git a/docs/source/index.rst b/docs/source/index.rst index 640de2a7..728e568c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -33,6 +33,7 @@ Documentation * :doc:`/getting-started/introduction` * :doc:`/getting-started/installation` * :doc:`/getting-started/quick-start` +* :doc:`/getting-started/dev-setup` .. toctree:: :hidden: @@ -42,6 +43,7 @@ Documentation getting-started/introduction getting-started/installation getting-started/quick-start + getting-started/dev-setup **Structure of OSeMOSYS in MUIO**