From a68554c8174e9d2030b596eba43753623df79c46 Mon Sep 17 00:00:00 2001 From: Micky <60691199+AliMickey@users.noreply.github.com> Date: Sun, 22 Dec 2024 21:31:10 +1100 Subject: [PATCH] test doc deployment --- .gitignore | 45 ++++++++++++ .readthedocs.yaml | 20 +++++ Dockerfile | 32 ++++++++ README.md | 48 +++++++++++- docs/conf.py | 44 +++++++++++ docs/configuration.rst | 161 +++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 41 +++++++++++ docs/installation.rst | 75 +++++++++++++++++++ docs/requirements.txt | 4 + 9 files changed, 468 insertions(+), 2 deletions(-) create mode 100644 .gitignore create mode 100644 .readthedocs.yaml create mode 100644 Dockerfile create mode 100644 docs/conf.py create mode 100644 docs/configuration.rst create mode 100644 docs/index.rst create mode 100644 docs/installation.rst create mode 100644 docs/requirements.txt diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3ce6884 --- /dev/null +++ b/.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 + diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..93e757e --- /dev/null +++ b/.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 diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..aa012bc --- /dev/null +++ b/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()"] diff --git a/README.md b/README.md index e4cf7c6..d73e39a 100644 --- a/README.md +++ b/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. \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..038ab18 --- /dev/null +++ b/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__' +} diff --git a/docs/configuration.rst b/docs/configuration.rst new file mode 100644 index 0000000..a2ac6d0 --- /dev/null +++ b/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. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..ccece45 --- /dev/null +++ b/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` diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..be16c97 --- /dev/null +++ b/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 + 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 \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..3fef161 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +sphinx +sphinx-rtd-theme +sphinx-autodoc-typehints +myst-parser