From fe24094f86c9b7ebfbdc4e5cd335e354dca604df Mon Sep 17 00:00:00 2001 From: Micky <60691199+AliMickey@users.noreply.github.com> Date: Wed, 25 Dec 2024 21:22:33 +1100 Subject: [PATCH] move docs to github for simplicity, cleanup a bunch of templates, prep for init release --- .gitignore | 10 +- .readthedocs.yaml | 14 -- README.md | 100 +++++++---- .../{default-favicon.svg => favicon.svg} | 0 .../{default-logo-dark.svg => logo-dark.svg} | 0 ...{default-logo-light.svg => logo-light.svg} | 0 app/static/js/main.js | 2 +- app/templates/base.html | 12 +- app/templates/footer.html | 23 +-- app/templates/index.html | 1 - app/views/main.py | 2 + docker-compose.yml | 10 ++ docs/conf.py | 44 ----- docs/configuration.rst | 161 ------------------ docs/index.rst | 41 ----- docs/installation.rst | 73 -------- docs/requirements.txt | 4 - 17 files changed, 92 insertions(+), 405 deletions(-) delete mode 100644 .readthedocs.yaml rename app/static/images/{default-favicon.svg => favicon.svg} (100%) rename app/static/images/{default-logo-dark.svg => logo-dark.svg} (100%) rename app/static/images/{default-logo-light.svg => logo-light.svg} (100%) create mode 100644 docker-compose.yml delete mode 100644 docs/conf.py delete mode 100644 docs/configuration.rst delete mode 100644 docs/index.rst delete mode 100644 docs/installation.rst delete mode 100644 docs/requirements.txt diff --git a/.gitignore b/.gitignore index 3ce6884..97065c0 100644 --- a/.gitignore +++ b/.gitignore @@ -1,14 +1,6 @@ # Config files -instance/ +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__/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml deleted file mode 100644 index 8f0b877..0000000 --- a/.readthedocs.yaml +++ /dev/null @@ -1,14 +0,0 @@ -version: 2 - -build: - os: ubuntu-24.04 - tools: - python: "3.11" - nodejs: "20" - -sphinx: - configuration: docs/conf.py - -python: - install: - - requirements: docs/requirements.txt \ No newline at end of file diff --git a/README.md b/README.md index d73e39a..5bb4076 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,84 @@ -# Looking Glass Network Management +# photonglass +A modern, distributed looking glass application that provides network insight for network operators. -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-Device Support**: Connect to multiple devices from one single interface. +-**Easy Deployment**: Extremely easy to deploy and scale with multiple devices. -- 🌐 **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 +## Setup (Docker) +1. Clone repository + - `git clone https://github.com/AliMickey/photonglass.git` +2. Create an instance folder to store your config and logos + - `cd photonglass` + - `mkdir instance` + - `mkdir instance/images` +3. Create config files and upload logos (follow config template below) +4. Edit `docker-compose.yml` if required (images path is commented out by default) +4. Build and deploy the container + - `docker compose up -d --build` +5. View the app at `http://IP_ADDRESS:5000`, recommend using a reverse proxy (traefik) for production use. -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 +### instance/config.yaml +``` +header: + title: "photonglass" + logo_href: "#" -The application uses YAML configuration files for customization: +footer: + text: "photonglass" + peeringdb_href: "https://www.peeringdb.com" + github_href: "https://github.com/alimickey" -- `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. +### instance/commands.yaml +``` +- id: "ping" + display_name: "Ping" + format: "ping -{ip_version} -c 4 {target}" + description: "Test network connectivity" + field: + type: "text" + placeholder: "Enter IP address or hostname" -## Contributing +- id: "traceroute" + display_name: "Traceroute" + format: "traceroute -{ip_version} {target}" + description: "Trace network path to destination" + field: + type: "text" + placeholder: "Enter IP address or hostname" -Contributions are welcome! Please read our [contributing guidelines](https://looking-glass.readthedocs.io/en/latest/contributing.html) before submitting pull requests. +- id: "mtr" + display_name: "MTR" + format: "mtr -{ip_version} -r {target}" + description: "Trace network path with stats" + field: + type: "text" + placeholder: "Enter IP address or hostname" +``` -## License +### instance/devices.yaml +``` +- id: "unique-sydney" + display_name: "Sydney" + subtext: "Equinix SY3" + country_code: "AU" + type: "linux" + host: "IP_ADDRESS" + port: PORT + username: "USERNAME" + password: "PASSWORD" + commands: + - ping + - traceroute + - mtr +``` -This project is licensed under the MIT License - see the LICENSE file for details. \ No newline at end of file + +## Attribution +This project was inspired by hyperglass after having difficulty deploying it. This project is not meant as a 1:1 replacement with hyperglass and as such is kept simple by design. At time of release only linux servers were tested as a target device, the same device library as hyperglass is used (netmiko) so compatibility with more devices should not be an issue, just be aware it is untested. \ No newline at end of file diff --git a/app/static/images/default-favicon.svg b/app/static/images/favicon.svg similarity index 100% rename from app/static/images/default-favicon.svg rename to app/static/images/favicon.svg diff --git a/app/static/images/default-logo-dark.svg b/app/static/images/logo-dark.svg similarity index 100% rename from app/static/images/default-logo-dark.svg rename to app/static/images/logo-dark.svg diff --git a/app/static/images/default-logo-light.svg b/app/static/images/logo-light.svg similarity index 100% rename from app/static/images/default-logo-light.svg rename to app/static/images/logo-light.svg diff --git a/app/static/js/main.js b/app/static/js/main.js index 58d47cf..084025c 100644 --- a/app/static/js/main.js +++ b/app/static/js/main.js @@ -5,7 +5,7 @@ const app = Vue.createApp({ selectedDevice: '', selectedCommand: '', targetIp: '', - selectedIpVersion: 'IPv4', // Default to IPv4 + selectedIpVersion: 'IPv4', isLoading: false, commandResult: '', devices: window.initialData?.devices || [], diff --git a/app/templates/base.html b/app/templates/base.html index 2e77114..bd377dc 100644 --- a/app/templates/base.html +++ b/app/templates/base.html @@ -3,9 +3,9 @@ - - - {{ config.site.title }} + + + {{ config.header.title }} @@ -30,9 +30,9 @@
- - Logo - + + Logo +
diff --git a/app/templates/footer.html b/app/templates/footer.html index 657a6d8..c41806a 100644 --- a/app/templates/footer.html +++ b/app/templates/footer.html @@ -20,12 +20,12 @@ - + PeeringDB - + @@ -90,24 +90,7 @@
-

- By using this Looking Glass service, you agree - to: -

-
    -
  • - Use the service responsibly and not for any - malicious purposes -
    • -
  • - Not attempt to overload or disrupt the - service -
    • -
  • - Respect the privacy and security measures in - place -
    • -
+

By using this Looking Glass service, you agree to use the service responsibly and not for any malicious purposes, not attempt to overload or disrupt the service, respect the privacy and security measures in place.

diff --git a/app/templates/index.html b/app/templates/index.html index 79407d5..5d798fe 100644 --- a/app/templates/index.html +++ b/app/templates/index.html @@ -145,7 +145,6 @@
-

Results

${commandResult}
diff --git a/app/views/main.py b/app/views/main.py index 2040b13..c5c9398 100644 --- a/app/views/main.py +++ b/app/views/main.py @@ -16,6 +16,7 @@ def index(): devices = load_yaml('devices') commands = load_yaml('commands') + # Remove sensitive data before passing to Jinja as additional security measure for device in devices: device.pop('username', None) device.pop('password', None) @@ -25,6 +26,7 @@ def index(): return render_template('index.html', config=config, devices=devices, commands=commands) +# Route to handle command execution requests @bp.route('/execute', methods=['POST']) @exception_handler def execute(): diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..306eb0f --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,10 @@ +services: + photonglass: + container_name: photonglass + restart: unless-stopped + build: . + ports: + - 5000:5000 + volumes: + - ./instance:/instance +# - ./instance/images:/app/static/images \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 038ab18..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,44 +0,0 @@ -# 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 deleted file mode 100644 index a2ac6d0..0000000 --- a/docs/configuration.rst +++ /dev/null @@ -1,161 +0,0 @@ -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 deleted file mode 100644 index ccece45..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,41 +0,0 @@ -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 deleted file mode 100644 index 05cbb7d..0000000 --- a/docs/installation.rst +++ /dev/null @@ -1,73 +0,0 @@ -Installation -=========== - -This guide covers Docker deployment options for photonglass. - -Requirements ------------ -* Docker and Docker Compose -* Network access to target devices - -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 deleted file mode 100644 index 3fef161..0000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,4 +0,0 @@ -sphinx -sphinx-rtd-theme -sphinx-autodoc-typehints -myst-parser