arifmahmudpranto/ampnm repository overview

⁠AMPNM - Advanced Multi-Protocol Network Monitor (Docker Version)

Real-time network monitoring system with visual topology mapping.

⁠🚀 Quick Start

Access at: http://localhost:2266⁠

Default Login:

• Username: admin
• Password: password (change in docker-compose.yml)

⁠🪟 Install AMPNM on Windows PC with Docker Desktop

For a seamless setup on Windows 11, you can use our PowerShell scripts or manually run the commands below.

⁠Manual Step-by-Step Instructions

1. Install Docker Desktop: Download and install Docker Desktop for Windows.
2. Enable WSL 2 Backend: Ensure "Use the WSL 2 based engine" is enabled during Docker Desktop setup.
3. Run Docker Desktop: Start the Docker Desktop application and wait until it indicates Docker is running.
4. Open PowerShell or Windows Terminal in the cloned repository directory:

   git clone https://github.com/pranto48/ampnm.git
   cd ampnm
   

   Copy
5. Set Environment Variables:
   • Copy .env.example to .env.
   • Customize .env as needed.
6. Start AMPNM:

   docker compose pull
   docker compose up --build --progress=plain -d
   

   Copy
7. Access the App: Open your browser at http://localhost:2266⁠ (or the port defined in APACHE_PORT).
8. Login:
   • Username: admin
   • Password: password
9. Change default passwords: Immediately modify the default admin password (ADMIN_PASSWORD) and database passwords in your .env file for security, then run the installer again.

⁠Additional Windows Command Utilities

• Stop services: Run .\scripts\windows-stop.ps1 to cleanly shut down containers.
• Update system: Run .\scripts\windows-update.ps1 to pull changes, fetch new images, and rebuild.
• Create database backup: Run .\scripts\windows-backup.ps1 to generate a timestamped SQL backup in the backups/ folder.

⁠📋 Requirements

• Docker & Docker Compose
• No other dependencies needed!

⁠✨ Features

• Real-time Monitoring: ICMP Ping, HTTP/HTTPS, TCP port checks
• Network Topology Map: Visual representation with status colors
• Alert System: Email notifications on status changes
• Historical Data: Track performance metrics over time
• Multi-User: Admin and viewer roles
• License Management: Built-in licensing system

⁠🔧 Configuration

⁠Environment Variables (docker-compose.yml)

environment:
  MYSQL_ROOT_PASSWORD: yourSecurePassword
  MYSQL_DATABASE: network_monitor
  DB_USER: ampnm_user
  DB_PASSWORD: yourDbPassword
  ADMIN_PASSWORD: yourAdminPassword
  APP_LICENSE_KEY: your-license-key

⁠Important Settings

• MYSQL_ROOT_PASSWORD: MySQL root password
• DB_PASSWORD: Application database password
• ADMIN_PASSWORD: Admin user password (default: password)
• APP_LICENSE_KEY: Your license key from portal

⁠📊 Monitoring Features

⁠Check Types

1. Windows Usage Agent (New Desktop Client)

   • Real-time CPU, RAM, and Disk metrics via Tauri desktop app
   • Network interface Tx/Rx tracking
   • Centralized status logging and process counting
   • Silent tray icon integration with pause options

2. ICMP Ping

   • Latency monitoring
   • Packet loss detection
   • TTL tracking
   • Thresholds: Warning & Critical

3. TCP Port Check

   • Port availability
   • Connection time
   • Service status

4. HTTP/HTTPS Check

   • Response code
   • Response time
   • Content verification

⁠Status Levels

• 🟢 Online: Device responding normally
• 🟡 Warning: Latency or packet loss threshold exceeded
• 🔴 Critical: Severe latency, packet loss, or offline
• ⚪ Offline: Device unreachable
• ⚫ Unknown: No data or unconfigured

⁠🗺️ Network Topology

• Drag-and-drop device placement
• Connection visualization
• Real-time status updates
• Color-coded indicators
• Custom icons and sizes
• Public map sharing option

⁠📧 Email Notifications

Configure SMTP settings to receive alerts:

1. Go to Email Notifications
2. Enter SMTP server details
3. Add recipient emails per device
4. Choose notification triggers:
   • Device goes online
   • Device goes offline
   • Warning status
   • Critical status

⁠🔐 Security

⁠Best Practices

1. Change Default Passwords

   ADMIN_PASSWORD: strong_password_here
   MYSQL_ROOT_PASSWORD: another_strong_password
   

   Copy

2. Restrict Port Access

   ports:
     - "127.0.0.1:2266:80"  # Only accessible from localhost
   

   Copy

3. Use HTTPS (Production)

   • Set up reverse proxy (Nginx/Apache)
   • Configure SSL certificates
   • Enable HTTPS redirects

4. Regular Backups

   docker exec ampnm-mysql mysqldump -u root -p network_monitor > backup.sql
   

   Copy

⁠🛠️ Advanced Configuration

⁠Custom Ping Intervals

Set per-device:

• Minimum: 10 seconds
• Default: 60 seconds
• Maximum: 3600 seconds (1 hour)

⁠Threshold Configuration

Warning Thresholds:

• Latency: 100ms default
• Packet Loss: 10% default

Critical Thresholds:

• Latency: 300ms default
• Packet Loss: 50% default

⁠📂 Docker Volumes

volumes:
  mysql-data: {}      # Database storage
  app-uploads: {}     # Icons, backgrounds, backups

⁠Backup Volumes

# Backup database
docker-compose exec mysql mysqldump -u root -p network_monitor > backup.sql

# Backup uploads
docker cp ampnm-app:/var/www/html/uploads ./uploads-backup

⁠🔄 Updates

# Pull latest image
docker-compose pull

# Restart with new image
docker-compose down
docker-compose up -d

⁠Automated update helpers

# Run safe update (captures pre-update state and optional DB dump)
./scripts/auto-update.sh

# Roll back to previous version snapshot

Rollback metadata and DB backups are stored in .update-state/<timestamp>/.

⁠🐛 Troubleshooting

⁠Ping Not Working

Issue: "sh: 1: ping: not found"

Solution: The Dockerfile has been updated to include iputils-ping. Rebuild:

docker-compose down
docker-compose build --no-cache
docker-compose up -d

⁠Database Connection Errors

# Check MySQL is running
docker-compose ps

# View logs
docker-compose logs mysql
docker-compose logs app

# Restart services
docker-compose restart

⁠Permission Issues

# Fix ownership
docker-compose exec app chown -R www-data:www-data /var/www/html

⁠Network Access Issues

# Check if container can ping external hosts
docker-compose exec app ping 8.8.8.8

# Check internal network
docker network inspect ampnm-network

⁠🛠️ Windows Docker Troubleshooting

Here are typical troubleshooting steps for common issues encountered on Windows environments:

⁠Docker Desktop not running

• Symptom: Script reports Docker is not running or commands time out.
• Fix: Launch Docker Desktop from the Start menu and wait until the status bar indicator turns green.

⁠WSL 2 not enabled

• Symptom: Docker Desktop fails to start, displaying a WSL 2 kernel update prompt.
• Fix: Open PowerShell as Administrator and run:

  wsl --install
  

  Copy
  Restart your computer if prompted.

⁠Port 2266 already in use

• Symptom: Apache fails to start, or container exits.
• Fix: Modify APACHE_PORT in your .env file to an unused port (e.g., APACHE_PORT=8080) and rerun the installer.

⁠MySQL container not healthy

• Symptom: Connection failures, loop redirecting back to database_setup.php.
• Fix: Verify logs and database state. Run docker compose ps to inspect. If the database volume was corrupted, reset it using the commands below.

⁠Docker pull unexpected EOF

• Symptom: Connection drop on large layers.
• Fix: Run docker compose pull --progress=plain to resume downloads.

⁠Cannot access http://localhost:2266⁠

• Symptom: Page not found.
• Fix: Ensure the containers are running:

  docker compose ps
  

  Copy
  If they are not running, check logs:

  docker compose logs -f app
  docker compose logs -f db
  

  Copy

⁠Ping/ICMP limitations inside Docker Desktop/Windows

• Symptom: Pings inside containers do not work or show 100% packet loss.
• Fix: Docker Desktop on Windows routes traffic through a user-space network translation layer that does not pass through low-level ICMP ping requests directly unless running with special permissions, or using the