NetAlertX/install/proxmox/README.md

NetAlertX Proxmox Installer

A comprehensive installer script for deploying NetAlertX on Proxmox VE (Debian-based) systems. This installer automates the complete setup including dependencies, NGINX configuration, systemd service, and security hardening.

🚀 Quick Start

Prerequisites

• Proxmox VE (Debian-based)
• Root access
• Internet connection

Installation

# Download and run the installer
curl -fsSL https://raw.githubusercontent.com/JVKeller/NetAlertX/main/install/proxmox/proxmox-install-netalertx.sh | bash

Non-Interactive Installation

# Skip all prompts and use defaults
NETALERTX_ASSUME_YES=1 curl -fsSL https://raw.githubusercontent.com/JVKeller/NetAlertX/main/install/proxmox/proxmox-install-netalertx.sh | bash

# Custom port
PORT=8080 NETALERTX_ASSUME_YES=1 curl -fsSL https://raw.githubusercontent.com/JVKeller/NetAlertX/main/install/proxmox/proxmox-install-netalertx.sh | bash

📋 What This Installer Does

System Dependencies

• PHP 8.4 with FPM, SQLite3, cURL extensions
• NGINX with custom configuration
• Python 3 with virtual environment
• Network tools: nmap, arp-scan, traceroute, mtr, speedtest-cli
• Additional tools: git, build-essential, avahi-daemon

Security Features

• Hardened permissions: Proper user/group ownership
• TMPFS mounts: Log and API directories mounted as tmpfs for security
• NGINX user: Configured to run as www-data
• Strict bash options: Error handling and security

Service Management

• Systemd service: Auto-start on boot with restart policies
• Service monitoring: Built-in health checks and logging
• Dependency management: Waits for network and NGINX

🔧 Configuration

Port Configuration

The installer prompts for a custom port (default: 20211) with a 10-second countdown:

Enter HTTP port for NetAlertX [20211] (auto-continue in 10s): 

Environment Variables

Variable	Description	Default
NETALERTX_ASSUME_YES	Skip all prompts	false
NETALERTX_FORCE	Force installation	false
PORT	Custom HTTP port	20211
LISTEN_ADDR	Bind address	0.0.0.0
ALWAYS_FRESH_INSTALL	Clear existing data	false

Service Management

# Check service status
systemctl status netalertx

# View logs
journalctl -u netalertx -f

# Restart service
systemctl restart netalertx

# Stop service
systemctl stop netalertx

🌐 Access

After installation, access NetAlertX at:

http://[SERVER_IP]:[PORT]

🔒 Security Considerations

TMPFS Mounts

• /app/log - Mounted as tmpfs (no persistent logs)
• /app/api - Mounted as tmpfs (temporary API data)

File Permissions

• Application files: www-data:www-data with appropriate permissions
• NGINX runs as www-data user
• Log directories: Secure permissions with tmpfs

Network Security

• NGINX configured for internal network access
• No external firewall rules added (configure manually if needed)

🛠️ Troubleshooting

Common Issues

403 Forbidden Error

# Check file permissions
ls -la /var/www/html/netalertx
ls -la /app/front

# Fix permissions
chown -R www-data:www-data /app/front
chmod -R 755 /app/front

Service Won't Start

# Check service status
systemctl status netalertx

# View detailed logs
journalctl -u netalertx --no-pager -l

# Check if port is in use
ss -tlnp | grep :20211

GraphQL Connection Issues

# Check API token in config
grep API_TOKEN /app/config/app.conf

# Verify GraphQL port
grep GRAPHQL_PORT /app/config/app.conf

# Check backend logs
tail -f /app/log/app.log

Log Locations

• Service logs: journalctl -u netalertx
• Application logs: /app/log/ (tmpfs)
• NGINX logs: /var/log/nginx/
• PHP logs: /app/log/app.php_errors.log

Manual Service Start

If systemd service fails:

# Activate Python environment
source /opt/myenv/bin/activate

# Start manually
cd /app
python server/

or

./start.netalertx.sh

🔄 Updates

Updating NetAlertX

# Stop service
systemctl stop netalertx

# Update from repository
cd /app
git pull origin main

# Restart service
systemctl start netalertx

📁 File Structure

/app/                          # Main application directory
├── front/                     # Web interface (symlinked to /var/www/html/netalertx)
├── server/                    # Python backend
├── config/                    # Configuration files
├── db/                        # Database files
├── log/                       # Log files (tmpfs)
├── api/                       # API files (tmpfs)
└── start.netalertx.sh        # Service startup script

/etc/systemd/system/
└── netalertx.service         # Systemd service definition

/etc/nginx/conf.d/
└── netalertx.conf            # NGINX configuration

🤝 Contributing

This installer will need a maintainer

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

🙏 Acknowledgments

• NetAlertX development team
• Proxmox VE community
• Debian/Ubuntu maintainers
• Open source contributors

---

Note: This installer was designed for a Proxmox LXC Debian 13 container. For other systems, please use the appropriate installer or manual installation instructions.