Skip to content

NetworkMonitor Developer Guide

Development Environment Setup

  1. Install system dependencies:
  2. Python 3.9 or later from python.org
  3. Npcap from npcap.com (Windows only)

  4. Node.js and npm for web interface development

  5. Clone the repository and set up a virtual environment: 

    git clone https://github.com/networkmonitor/networkmonitor.git
cd networkmonitor
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  6. Install development dependencies: 

    pip install -r requirements.txt
pip install -r requirements-build.txt

  7. Install web interface dependencies: 

    cd networkmonitor/web
npm install

Prerequisites

System Requirements

  • Windows 10 or later (64-bit)
  • Python 3.9 or later
  • Npcap for packet capture (Windows)
  • Make sure to select "Install Npcap in WinPcap API-compatible Mode" during installation

Required Software

  • Python 3.8 or higher
  • pip (Python package manager)
  • Git

Windows-specific Requirements

1. NSIS (Nullsoft Scriptable Install System)

  • Download from: https://nsis.sourceforge.io/Download
  • Run the installer and select full installation
  • Add NSIS installation directory to PATH (usually C:\Program Files (x86)\NSIS)
  • Install required NSIS plugins:
    1. Download EnvVarUpdate plugin: https://nsis.sourceforge.io/mediawiki/images/7/7f/EnvVarUpdate.7z
    2. Extract the files to your NSIS installation:
      • Copy Include\EnvVarUpdate.nsh to C:\Program Files (x86)\NSIS\Include
      • Copy Plugin\x86-ansi\EnvVarUpdate.dll to C:\Program Files (x86)\NSIS\Plugins\x86-ansi
      • Copy Plugin\x86-unicode\EnvVarUpdate.dll to C:\Program Files (x86)\NSIS\Plugins\x86-unicode

2. GTK3 Runtime (for icon conversion)

  • Download GTK3 runtime installer: https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
  • Run the installer and select Complete installation
  • IMPORTANT: Make sure to check "Add to PATH" option during installation
  • After installation, verify that the GTK3 bin directory (e.g., C:\Program Files\GTK3-Runtime Win64\bin) is in your PATH
  • Restart your terminal/IDE after installation
  • To verify installation: Open a new command prompt and run gdk-pixbuf-query-loaders --version
  • If you continue to have issues with Cairo:
    1. Download the latest GTK3 bundle from MSYS2: https://www.msys2.org/
    2. Install MSYS2
    3. Open MSYS2 terminal and run: pacman -S mingw-w64-x86_64-gtk3 mingw-w64-x86_64-cairo
    4. Add the MSYS2 bin directory to your PATH (e.g., C:\msys64\mingw64\bin)

3. Visual C++ Build Tools

  • Download Visual Studio Build Tools: https://visualstudio.microsoft.com/visual-cpp-build-tools/
  • Run the installer and select:
    • C++ build tools
    • Windows 10 SDK
    • Python development support (optional)

For Linux Users

  • Install system packages: 
    sudo apt install net-tools iptables tcpdump

Ubuntu/Linux Requirements

1. System Dependencies

# Install basic build dependencies
sudo apt update
sudo apt install -y build-essential python3-dev python3-pip

# Install Cairo and GTK3 for icon conversion
sudo apt install -y libcairo2-dev libgirepository1.0-dev pkg-config

# Install networking tools
sudo apt install -y net-tools iptables tcpdump

# Install NSIS (for creating installers on Linux)
sudo apt install -y nsis

2. Python Libraries

pip3 install cairosvg pillow pyinstaller

For macOS Users

  • Install Homebrew packages: 
    brew install libpcap tcpdump

macOS Requirements

1. System Dependencies

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install cairo pkg-config
brew install gtk+3
brew install python3

# Optional: Install NSIS (for cross-building Windows installers)
brew install makensis

2. Python Libraries

pip3 install cairosvg pillow pyinstaller

Python Dependencies

  1. Create and activate a virtual environment: 

    python -m venv venv
source venv/bin/activate  # On Linux/Mac
venv\Scripts\activate     # On Windows

  2. Install runtime dependencies: 

    pip install -r requirements.txt

  3. Install build dependencies (only needed for packaging): 

    pip install -r requirements-build.txt

Setup Development Environment

  1. Create and activate a virtual environment: 

    python -m venv venv
# Windows
venv\Scripts\activate
# Linux/macOS
source venv/bin/activate

  2. Install runtime dependencies: 

    pip install -r requirements.txt

  3. Install build dependencies (only needed for packaging): 

    pip install -r requirements-build.txt

Running for Development

Run the application in debug mode: 

python start_networkmonitor.py

Or use the batch file on Windows (includes additional debug output): 

run_networkmonitor.bat

Building from Source

  1. Clone the repository: 

    git clone https://github.com/umerfarok/networkmonitor.git
cd networkmonitor

  2. Build the package: 

    python build.py

The build process will: 1. Clean previous builds 2. Convert SVG icon to ICO format (if GTK3 runtime is installed) 3. Create a standalone executable 4. Create an installer (on Windows, if NSIS is installed)

Build outputs will be available in the dist directory: - Windows: NetworkMonitor.exe and NetworkMonitor_Setup_0.1.0.exe - Linux: NetworkMonitor executable - macOS: NetworkMonitor executable or .app bundle

Platform-Specific Build Notes

Linux (Ubuntu/Debian)

Building on Linux creates a standalone executable that can be run on similar Linux distributions: 

# Make the executable executable
chmod +x dist/NetworkMonitor
# Run the application
sudo ./dist/NetworkMonitor

macOS

Building on macOS creates a standalone executable: 

# Make the executable executable
chmod +x dist/NetworkMonitor
# Run the application
sudo ./dist/NetworkMonitor

Windows

The Windows executable requires Administrator privileges to run properly: - Right-click on the executable - Select "Run as Administrator"

Common Build Issues

Icon Conversion Issues

If you see "cairo library not found" errors: 1. Make sure GTK3 is properly installed as described in the prerequisites 2. Verify that GTK3 bin directory is in your PATH environment variable 3. Install Python packages: pip install cairosvg Pillow 4. Try installing Cairo directly: pip install pycairo 5. For Windows, consider using MSYS2 to install Cairo: - Install MSYS2: https://www.msys2.org/ - Run: pacman -S mingw-w64-x86_64-cairo 6. Restart your terminal/IDE completely (not just the command prompt) 7. Run build again

NSIS Issues

If installer creation fails: 1. Ensure NSIS is installed and in PATH 2. Install EnvVarUpdate plugin as described in prerequisites (Windows only) 3. Check if the NSIS Include and Plugins directories contain the required files 4. Run makensis -VERSION in terminal to verify NSIS is accessible

Missing DLL Errors

If you see missing DLL errors when running the built executable: 1. Windows: Install Visual C++ Redistributable 2015-2022 2. Linux: Install required system libraries using apt 3. macOS: Install required libraries using brew 4. Ensure all dependencies are installed: pip install -r requirements.txt

Development Guidelines

Code Style

  • Follow PEP 8 guidelines
  • Use type hints where possible
  • Document public functions and classes

Testing

python -m pytest tests/

Adding Dependencies

  1. Add runtime dependencies to requirements.txt
  2. Add build dependencies to requirements-build.txt
  3. Update setup.py for runtime dependencies

Dependency Management

  1. Keep dependencies organized:
  2. requirements.txt: Runtime dependencies
  3. requirements-build.txt: Build-time dependencies

  4. package.json: Web interface dependencies

  5. Version constraints:

  6. Use >= for minimum version requirements
  7. Test thoroughly with latest versions

  8. Document any version-specific issues

  9. System dependencies:

  10. Document clearly in README.md
  11. Provide detailed installation instructions
  12. Include version requirements

Testing

  1. Test installation scenarios:
  2. Clean Windows installation
  3. Various Python versions
  4. Different Npcap versions

  5. With/without admin rights

  6. Test dependency checks:

  7. Missing Python
  8. Missing Npcap
  9. Missing packages
  10. Version conflicts

Error Handling

Implement graceful fallbacks and clear error messages for: 1. Missing system dependencies 2. Package installation failures 3. Permission issues 4. Version compatibility problems

Releasing

  1. Update version in:
  2. setup.py
  3. build.py

  4. networkmonitor/__init__.py

  5. Create a new build: 

    python build.py

  6. Test the installer from dist directory

Release Process

  1. Update version numbers:
  2. pyproject.toml
  3. installer.nsi

  4. package.json

  5. Build release artifacts: 

    python build.py

  6. Test installation package:

  7. Fresh Windows installation
  8. Different Python versions
  9. Verify dependency handling

  10. Check error messages

  11. Create release checklist:

  12. Version numbers updated
  13. Changelog updated
  14. Dependencies documented
  15. Installation tested
  16. Release notes complete

Troubleshooting

Build Environment Issues

  • Run python -m pip check to verify dependencies
  • Use python -m pip install --upgrade pip setuptools wheel to update basic tools
  • Clear pip cache if needed: python -m pip cache purge

Installation Issues

  • Run the installer as Administrator (Windows)
  • Run with sudo on Linux/macOS
  • Check system logs for installation errors

Runtime Issues

  • Check logs in networkmonitor.log
  • Run with --debug flag for verbose output
  • Verify all dependencies are installed

Project Structure

networkmonitor/
├── __init__.py         # Package initialization
├── cli.py             # Command-line interface
├── dependency_check.py # Dependency verification
├── launcher.py        # Application launcher
├── monitor.py         # Core monitoring functionality
├── npcap_helper.py    # Windows Npcap support
├── server.py          # Web server component
├── splash.py          # Splash screen UI
└── web/              # Web interface files

UI Components

Status Dashboard

The status dashboard is built using Tkinter with a modern, dark theme design. The implementation can be found in run_app.py and launcher.py. Here are the key technical details:

Color Scheme

The UI uses a consistent color scheme defined as: - Background: #1e1e1e (Dark background) - Foreground: #e0e0e0 (Light text) - Accent: #007acc (Blue accent) - Success: #2ecc71 (Green) - Error: #e74c3c (Red) - Warning: #f1c40f (Yellow) - Header Background: #252526 - Button Background: #333333 - Button Hover: #404040

UI Components Structure

  1. Header Section
  2. Professional gradient background effect
  3. Centered title with Segoe UI bold font
  4. Application icon integration

  5. Fixed height with proper padding

  6. Status Section

  7. Dynamic status indicator with smooth color transitions
  8. Clear status message display
  9. Color-coded states (running/error/warning)

  10. Background highlighting for better visibility

  11. URL Display

  12. Interactive URL label with hover effects
  13. One-click copy functionality
  14. Visual feedback on interactions

  15. Direct browser launch capability

  16. Control Panel

  17. Modern flat-design buttons
  18. Consistent button sizing and spacing
  19. Hover effects for better UX
  20. Background operation support
  21. Safe exit handling

System Tray Integration

The application now supports system tray operation with: - Custom tray icon display - Right-click context menu - Status preservation while minimized - Quick restore functionality - Clean application exit

Implementation Guidelines

  1. Window Configuration
  2. Minimum size: 500x300 pixels
  3. Responsive layout adaptation
  4. DPI-aware scaling
  5. Multi-monitor support

  6. Proper window manager hints

  7. Font Usage

  8. Primary UI: Segoe UI (Windows system font)
  9. Fallback fonts for cross-platform compatibility
  10. Size scaling based on screen resolution

  11. Consistent font weights

  12. Layout Standards

  13. Standard padding: 20px horizontal, 15px vertical
  14. Consistent component spacing
  15. Proper alignment and anchoring

  16. Responsive grid system

  17. Event Handling

  18. Non-blocking UI operations
  19. Threaded server management
  20. Periodic status updates
  21. Clean exit procedures
  22. Error handling and recovery

Development Guidelines

Adding New UI Elements

  1. Follow the color scheme: 

    element = tk.Widget(
    parent,
    bg=COLORS['bg'],
    fg=COLORS['fg'],
    activebackground=COLORS['button_hover']
)

  2. Use the button creation helper: 

    new_button = create_button(
    text="Action",
    command=handler_function,
    width=15
)

  3. Status Updates: 

    def update_status(state, message):
    # Update indicator color
    color = COLORS[state] if state in COLORS else COLORS['warning']
    status_indicator.update_color(color)
    # Update message
    status_var.set(message)
    # Trigger UI update
    root.update_idletasks()

Testing Requirements

  1. Visual Testing
  2. Window sizing and minimum constraints
  3. HiDPI display compatibility
  4. Color contrast verification
  5. Animation smoothness

  6. Font rendering quality

  7. Functionality Testing

  8. Button interactions
  9. Status updates
  10. URL handling
  11. Copy functionality
  12. System tray operations

  13. Exit handling

  14. Performance Testing

  15. UI responsiveness
  16. Memory usage
  17. CPU utilization
  18. Thread management
  19. Resource cleanup

Build Requirements

Ensure all UI-related dependencies are installed:

pip install -r requirements.txt

Critical packages: - tkinter (built into Python) - pystray>=0.19.0 (system tray support) - Pillow>=10.0.0 (image processing)

Contribution Guidelines

  1. UI Changes
  2. Maintain dark theme consistency
  3. Follow existing color scheme
  4. Use proper padding and spacing
  5. Ensure responsive behavior

  6. Add appropriate documentation

  7. Code Style

  8. Follow PEP 8 guidelines
  9. Document all UI components
  10. Use type hints where applicable
  11. Include error handling

  12. Write modular, reusable code

  13. Pull Requests

  14. Include UI screenshots if applicable
  15. Document visual changes
  16. Test across different resolutions
  17. Verify system tray functionality
  18. Check resource usage

Developer Documentation

Developer Guide

Setup Development Environment

  1. Prerequisites:
  2. Python 3.9 or later
  3. Npcap (Windows only)

  4. Git

  5. Clone and Setup: 

    git clone https://github.com/umerfarok/netmoniter.git
cd netmoniter
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows
pip install -r requirements.txt
pip install -r requirements-build.txt

Building

python build.py

Testing

python -m pytest tests/

Contributing

See CONTRIBUTING.md for guidelines.