NetAlertX Deployment & Usage Guide

1. Prerequisites

System Requirements

• Docker (recommended) or Python 3.8+
• Network access to the monitored subnet(s)
• Storage: Persistent volume for database and configuration
• Permissions: Ability to run network scans (ARP, nmap) - may require root/sudo for some scanners

Required Tools & Accounts

• Docker Engine or Docker Compose
• Git (for source installation)
• Optional: Home Assistant (for addon installation)
• Optional accounts for notification services:
  • Apprise (supports 80+ services)
  • Pushsafer, Pushover, or NTFY (native support)
  • Telegram (via Apprise)

2. Installation

Docker (Recommended)

# Create data directory structure
mkdir -p /local_data_dir/config /local_data_dir/db

# Run NetAlertX container
docker run -d \
  --network=host \
  --restart unless-stopped \
  -v /local_data_dir:/data \
  -v /etc/localtime:/etc/localtime:ro \
  --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
  -e PORT=20211 \
  -e APP_CONF_OVERRIDE='{"GRAPHQL_PORT":"20214"}' \
  ghcr.io/netalertx/netalertx:latest

Docker Compose (From Source)

git clone https://github.com/netalertx/NetAlertX.git
cd NetAlertX
docker compose up --force-recreate --build
# Customize docker-compose.yaml as needed, then re-run

Home Assistant Addon

1. In Home Assistant, go to Settings → Add-ons
2. Click Add-on Store (bottom right)
3. Click the three dots menu → Repositories
4. Add: https://github.com/alexbelgium/hassio-addons
5. Find NetAlertX in the new repository and install

3. Configuration

Environment Variables

Configuration Files

After first run, configure via the web interface at http://your-server:20211:

1. Network Settings: Configure scan ranges and intervals

2. Discovery Methods: Enable/disable scanners:

   • ARP scan
   • Pi-hole database import
   • DHCP leases import
   • UNIFI controller import
   • SNMP router import
   • Custom plugins

3. Notification Setup:

   • Configure Apprise for 80+ services
   • Set up native Pushsafer/Pushover/NTFY
   • Define notification triggers

4. Device Categorization:

   • Define device groups
   • Set up automatic classification rules
   • Configure vendor mappings

API Keys & External Services

• Notification Services: Obtain API keys from your chosen provider
• Network Controllers: Credentials for UNIFI, SNMP, Pi-hole imports
• External Integrations: Home Assistant tokens, webhook URLs

4. Build & Run

Development Environment

# Clone repository
git clone https://github.com/netalertx/NetAlertX.git
cd NetAlertX

# Install Python dependencies
pip install -r requirements.txt

# Set up database
python3 init_db.py

# Run in development mode
python3 main.py --dev

Production Build (Docker)

# Build custom image
docker build -t netalertx:custom .

# Run with custom configuration
docker run -d \
  --network=host \
  -v $(pwd)/data:/data \
  -e PORT=8080 \
  netalertx:custom

Plugin Development

# Plugin structure
plugins/
├── your_plugin/
│   ├── plugin.py          # Main plugin logic
│   ├── config.json        # Plugin configuration
│   └── README.md          # Documentation

# Test plugin
python3 -m server.plugin_helper test your_plugin

5. Deployment

Platform Recommendations

Single Server (Recommended)

• Docker on Linux server
• Port: 20211 (default)
• Network mode: host for best network visibility
• Storage: Persistent volume for /data

Home Assistant

• Use the official addon repository
• Automatic updates via Supervisor
• Integrated with HA automations

Kubernetes/Cloud

# Sample Kubernetes deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: netalertx
spec:
  replicas: 1
  selector:
    matchLabels:
      app: netalertx
  template:
    metadata:
      labels:
        app: netalertx
    spec:
      hostNetwork: true  # Required for network scanning
      containers:
      - name: netalertx
        image: ghcr.io/netalertx/netalertx:latest
        ports:
        - containerPort: 20211
        volumeMounts:
        - mountPath: /data
          name: data
        env:
        - name: PORT
          value: "20211"
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: netalertx-data

Reverse Proxy Setup

# Nginx configuration
server {
    listen 80;
    server_name netalertx.yourdomain.com;
    
    location / {
        proxy_pass http://localhost:20211;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Scaling Considerations

• Single instance sufficient for most networks (up to 1000+ devices)
• Database: SQLite works for most deployments; consider PostgreSQL for very large networks
• Scan intervals: Adjust based on network size and sensitivity to changes

6. Troubleshooting

Common Issues

Container Won't Start

# Check Docker logs
docker logs <container_id>

# Verify port availability
netstat -tulpn | grep :20211

# Check volume permissions
ls -la /local_data_dir/
# Should be writable by UID 20211

Network Scanning Not Working

# Test ARP scanning manually
sudo arp-scan --localnet

# Check container network mode
docker inspect <container_id> | grep NetworkMode

# Verify you're using --network=host

Web Interface Not Accessible

1. Check firewall: sudo ufw status
2. Verify port binding: docker ps shows 0.0.0.0:20211->20211/tcp
3. Check logs for errors: docker logs <container_id>

Database Issues

# Backup database
cp /local_data_dir/db/app.db /local_data_dir/db/app.db.backup

# Check database integrity
sqlite3 /local_data_dir/db/app.db "PRAGMA integrity_check;"

# Reset if needed (will lose data)
rm /local_data_dir/db/app.db
# Restart container to regenerate

Plugin Errors

1. Check plugin configuration in web interface
2. View plugin logs: tail -f /local_data_dir/logs/plugins.log
3. Test plugin manually: python3 -m server.plugin_helper debug <plugin_name>

Logs & Diagnostics

# View application logs
docker logs -f <container_id>

# Access logs directly
tail -f /local_data_dir/logs/app.log

# Check specific log files:
# - app_front.log: Frontend issues
# - IP_changes.log: IP address changes
# - execution_queue.log: Plugin execution
# - db_is_locked.log: Database lock issues

Performance Issues

1. High CPU: Reduce scan frequency in Settings → Scan Frequency
2. Slow UI: Check database size; consider archiving old events
3. Memory issues: Limit scan ranges; exclude non-essential IP ranges

Getting Help

• Discord: Join NetAlertX Discord
• Documentation: Full docs at netalertx.com
• GitHub Issues: Report bugs
• Migration Guide: If upgrading from v2.55.24

Quick Fixes

# Restart container
docker restart <container_id>

# Update to latest version
docker pull ghcr.io/netalertx/netalertx:latest

# Reset configuration (backup first!)
rm -rf /local_data_dir/config/*
# Restart container to regenerate defaults

Remember to always backup your /local_data_dir before making significant changes or updates.