test doc deployment

.gitignore

@@ -0,0 +1,45 @@
+# Config files
+instance/
+
+docker-compose.yml
+
+# Static files
+app/static/images/**
+!app/static/images/
+!app/static/images/default-logo-dark.svg
+!app/static/images/default-logo-light.svg
+!app/static/images/default-favicon.svg
+
+# Python
+app/__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+
+# Environment
+.env
+.venv
+env/
+venv/
+
+# Node
+node_modules/
+dist/
+.npm
+app/static/css/styles.css
+
+# IDE
+.idea/
+.vscode/
+*.sublime-*
+*.swp
+*.swo
+
+# Logs
+*.log
+logs/
+
+# System
+.DS_Store
+Thumbs.db
+

.readthedocs.yaml

@@ -0,0 +1,20 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.11"
+    nodejs: "20"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: app/requirements.txt
+    - method: pip
+      path: .
+
+formats:
+  - pdf
+  - epub

Dockerfile

@@ -0,0 +1,32 @@
+
+FROM python:3.11-slim-bookworm
+
+# Install Node.js
+RUN apt-get update && apt-get install -y nodejs npm \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONPATH=/
+
+WORKDIR /app
+
+# Install Python dependencies
+COPY app/requirements.txt /app/
+RUN pip install --no-cache-dir -r /app/requirements.txt
+
+# Install Node.js dependencies and build TailwindCSS
+COPY package*.json /app/
+RUN npm install
+
+COPY app/ /app/
+
+# Build TailwindCSS
+RUN npx tailwindcss -i ./static/css/input.css -o ./static/css/styles.css --minify
+
+RUN groupadd --system appuser && useradd --system --create-home --gid appuser appuser
+USER appuser
+
+EXPOSE 5000
+
+CMD ["gunicorn", "--bind", "0.0.0.0:5000", "--workers", "4", "--worker-class", "gthread", "--threads", "2", "--timeout", "60", "app:create_app()"]

README.md

@@ -1,2 +1,46 @@
-# photonglass
-Modern, simple, distributed looking glass application
+# Looking Glass Network Management
+
+A modern web-based looking glass application that provides infrastructure monitoring and administration capabilities for network professionals. Built with Flask and Vue.js, this platform delivers real-time network analysis through an intuitive browser-based interface.
+
+## Features
+
+- 🌐 **Multi-Location Support**: Monitor network performance across different geographical locations
+- 🔍 **Network Diagnostics**: Execute common network commands (ping, traceroute, MTR)
+- 🎨 **Modern UI**: Clean, responsive interface with dark/light mode support
+- 🔒 **Secure Command Execution**: Built-in input validation and command sanitization
+- ⚡ **Real-Time Updates**: WebSocket-based live data streaming
+- 📱 **Responsive Design**: Optimized for both desktop and mobile devices
+- 🎯 **BGP Community Lookup**: Advanced BGP routing information
+- 🔄 **Docker Support**: Easy deployment with containerization
+
+## Quick Start
+
+See our [installation guide](https://looking-glass.readthedocs.io/en/latest/installation.html) for detailed setup instructions.
+
+## Documentation
+
+Full documentation is available at [looking-glass.readthedocs.io](https://looking-glass.readthedocs.io/).
+
+Key documentation sections:
+- [Installation Guide](https://looking-glass.readthedocs.io/en/latest/installation.html)
+- [Configuration Options](https://looking-glass.readthedocs.io/en/latest/configuration.html)
+- [Usage Guide](https://looking-glass.readthedocs.io/en/latest/usage.html)
+- [API Documentation](https://looking-glass.readthedocs.io/en/latest/api.html)
+
+## Configuration
+
+The application uses YAML configuration files for customization:
+
+- `instance/config.yaml`: Core application settings
+- `instance/commands.yaml`: Network command definitions
+- `instance/devices.yaml`: Network device configurations
+
+See the [configuration documentation](https://looking-glass.readthedocs.io/en/latest/configuration.html) for detailed options.
+
+## Contributing
+
+Contributions are welcome! Please read our [contributing guidelines](https://looking-glass.readthedocs.io/en/latest/contributing.html) before submitting pull requests.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

docs/conf.py

@@ -0,0 +1,44 @@
+# Configuration file for the Sphinx documentation builder.
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+
+# Project information
+project = 'photonglass'
+copyright = '2024, photonglass'
+author = 'AliMickey'
+release = '1.0.0'
+
+# General configuration
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.githubpages',
+    'sphinx_rtd_theme',
+    'sphinx.ext.intersphinx',
+    'myst_parser'
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# HTML output options
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+html_title = 'Looking Glass Documentation'
+
+# Intersphinx configuration
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'flask': ('https://flask.palletsprojects.com/en/2.3.x/', None),
+}
+
+# autodoc configuration
+autodoc_default_options = {
+    'members': True,
+    'member-order': 'bysource',
+    'special-members': '__init__',
+    'undoc-members': True,
+    'exclude-members': '__weakref__'
+}

docs/configuration.rst

@@ -0,0 +1,161 @@
+Configuration
+============
+
+This section details all configuration options available in the Looking Glass application.
+
+Core Configuration (config.yaml)
+------------------------------
+
+The ``instance/config.yaml`` file contains core application settings and UI customization options.
+
+Site Settings
+~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+    site:
+      title: "photonglass"  # Application title displayed in browser
+      favicon: "/static/images/default-favicon.svg"  # Site favicon path
+
+Logo Configuration
+~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+    logo:
+      dark: "/static/images/default-logo-dark.svg"   # Logo for dark mode
+      light: "/static/images/default-logo-light.svg" # Logo for light mode
+
+Footer Settings
+~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+    footer:
+      text: "photonglass"  # Footer text
+      external_links:      # External links in footer
+        peeringdb: "https://www.peeringdb.com"
+        github: "https://github.com/AliMickey/photonglass" # For credit, remove if you want :)
+
+Network Commands (commands.yaml)
+-----------------------------
+
+The ``instance/commands.yaml`` file defines available network diagnostic commands and their parameters.
+
+Command Definition Format
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Each command is defined with the following structure:
+
+.. code-block:: yaml
+
+    - id: "command_id"              # Unique identifier for the command
+      display_name: "Command Name"  # Display name in the UI
+      format: "command {target}"    # Command format with placeholders
+      description: "Description"    # Command description
+      field:                       # Input field configuration
+        type: "text"              # Input field type
+        placeholder: "Enter..."   # Placeholder text
+
+Available Commands
+~~~~~~~~~~~~~~~~
+
+Ping Command
+^^^^^^^^^^^
+
+.. code-block:: yaml
+
+    - id: "ping"
+      display_name: "Ping"
+      format: "ping -c 4 {target}"
+      description: "Test network connectivity"
+      field:
+        type: "text"
+        placeholder: "Enter IP address or hostname"
+
+Traceroute Command
+^^^^^^^^^^^^^^^^^
+
+.. code-block:: yaml
+
+    - id: "traceroute"
+      display_name: "Traceroute"
+      format: "traceroute {target}"
+      description: "Trace network path to destination"
+      field:
+        type: "text"
+        placeholder: "Enter IP address or hostname"
+
+MTR Command
+^^^^^^^^^^
+
+.. code-block:: yaml
+
+    - id: "mtr"
+      display_name: "MTR"
+      format: "mtr -r {target}"
+      description: "My Traceroute - Network diagnostic tool"
+      field:
+        type: "text"
+        placeholder: "Enter IP address or hostname"
+
+Network Devices (devices.yaml)
+---------------------------
+
+The ``instance/devices.yaml`` file contains network device configurations and access control settings.
+
+Device Configuration Format
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+    - id: "device_id"                  # Unique device identifier
+      name: "Device Name"             # Display name
+      type: "router/switch"          # Device type
+      location: "Location Name"      # Physical location
+      host: "192.168.1.1"             # Management IP address
+      port: 22                        # SSH port
+      credentials:                   # Access credentials
+        username: "admin"
+        key_file: "/path/to/key"    # SSH key file path
+      commands:                     # List of allowed commands
+          - "ping"
+          - "traceroute"
+
+
+Security Recommendations
+---------------------
+
+1. Credentials and Secrets
+   - Never commit sensitive information to version control
+   - Use environment variables for secrets
+   - Regularly rotate credentials
+
+2. Network Access
+   - Implement strict ACLs for command targets
+   - Use allowlists for permitted networks
+   - Rate limit command execution
+
+3. Authentication
+   - Enable HTTPS in production
+   - Implement user authentication if needed
+   - Use strong password policies
+
+4. Monitoring
+   - Enable logging for all command executions
+   - Monitor system resources
+   - Set up alerts for suspicious activities
+
+For more information about security best practices, refer to the :doc:`security` section.
+
+Custom Commands
+~~~~~~~~~~~~~
+
+To add custom network commands:
+
+1. Add command definition to ``commands.yaml``
+2. Implement command validation if needed
+3. Update the UI help documentation
+4. Test the command execution
+
+Refer to the :doc:`development` section for more details about extending the application.

docs/index.rst

@@ -0,0 +1,41 @@
+Welcome to Looking Glass Documentation
+====================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   introduction
+   installation
+   configuration
+   usage
+   api
+   development
+   contributing
+   changelog
+
+Introduction
+-----------
+Looking Glass is a modern web application for Internet Service Providers (ISPs) that provides network command execution capabilities. It allows network operators and customers to perform various network diagnostic commands in a secure and controlled manner.
+
+Quick Start
+----------
+Check out the :doc:`installation` guide to get started with Looking Glass.
+
+Features
+--------
+* Modern web interface built with Flask and TailwindCSS
+* Secure command execution with input validation
+* Support for multiple network diagnostic commands:
+  * Ping
+  * Traceroute
+  * MTR
+* Configurable command permissions and validation rules
+* Easy to deploy and maintain
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/installation.rst

@@ -0,0 +1,75 @@
+Installation
+===========
+
+This guide covers both standard installation and Docker deployment options for the Looking Glass application.
+
+Requirements
+-----------
+* Python 3.7 or higher (for standard installation)
+* Node.js and npm (for standard installation)
+* Docker and Docker Compose (for Docker deployment)
+* Network access to target devices
+
+Docker Deployment
+---------------
+
+1. Clone the repository::
+
+    git clone <repository-url>
+    cd looking-glass
+
+2. Configure the application::
+
+    cp instance/config.yaml.example instance/config.yaml
+    cp instance/commands.yaml.example instance/commands.yaml
+    cp instance/devices.yaml.example instance/devices.yaml
+
+3. Build and start the containers::
+
+    docker compose up -d
+
+   This will:
+   - Build the application image
+   - Start the web application container
+   - Initialize the TailwindCSS build process
+
+4. Access the application at ``http://localhost:5000``
+
+Configuration Files
+-----------------
+
+The application uses three main configuration files:
+
+1. ``instance/config.yaml``
+   - Core application settings
+   - UI customization
+   - Logging configuration
+
+2. ``instance/commands.yaml``
+   - Network diagnostic commands
+   - Command parameters and validation rules
+   - Output formatting options
+
+3. ``instance/devices.yaml``
+   - Network device definitions
+   - Authentication credentials
+   - Access control rules
+
+See the :doc:`configuration` section for detailed configuration options.
+
+Security Considerations
+---------------------
+
+1. Always change default credentials
+2. Use strong passwords for database and application access
+3. Configure appropriate network access controls
+4. Regularly update dependencies
+5. Monitor application logs for security events
+
+Next Steps
+---------
+After installation, refer to:
+
+- :doc:`configuration` for detailed setup options
+- :doc:`usage` for operation instructions
+- :doc:`api` for API documentation

docs/requirements.txt

@@ -0,0 +1,4 @@
+sphinx
+sphinx-rtd-theme
+sphinx-autodoc-typehints
+myst-parser