Maintenance Scripts

NexusPanel ships with six command-line scripts for managing, monitoring, and troubleshooting your installation. All scripts are located in /opt/nexuspanel/ and must be run as root (sudo).

Quick Reference

1. Troubleshoot — troubleshoot.sh

The most powerful diagnostic tool. Runs 30+ checks across 8 categories and can auto-repair issues.

sudo bash troubleshoot.sh           # Diagnostic report only
sudo bash troubleshoot.sh --repair  # Interactive fix mode
sudo bash troubleshoot.sh --yes     # Full auto-repair, no prompts

Checks Performed

• System Info — OS version, kernel, memory %, disk %, CPU load vs cores
• Dependencies — Node.js, npm, git, nginx, certbot, Docker, PostgreSQL, ClamAV
• Services — nexuspanel status (running/stopped/enabled), nginx, docker. Shows recent journalctl logs if stopped
• Application Integrity — .env validation (LICENSE_KEY, JWT_SECRET, DOMAIN, PORT), node_modules, data/ directory
• Network — Port listening status, firewall rules, license server connectivity, DNS resolution
• Nginx — Config presence, syntax check, recent error log entries
• Logs — Recent error scan in journalctl
• Auto Repair — Restarts service, installs npm deps, opens firewall ports

Example Output

━━━ System Information ━━━
  ✓ OS: AlmaLinux 10.2 (almalinux)
  ✓ Kernel: 6.12.0
  ✓ Memory: 2048M / 4096M (50%)
  ✓ Disk: 34% used (45G free)
  ✓ CPU Load: 0.45 (22%)

━━━ Services ━━━
  ✓ nexuspanel: RUNNING
  ✓ nginx: RUNNING

============================================================
  ✓ All checks passed — NexusPanel is healthy

2. Log Viewer — logs.sh

View, follow, filter, and search across all NexusPanel log sources in one command.

sudo bash logs.sh                    # Last 50 lines of service logs
sudo bash logs.sh -f                 # Follow logs in real-time
sudo bash logs.sh -n 200             # Show last 200 lines
sudo bash logs.sh -s "error"         # Filter lines containing "error"
sudo bash logs.sh --all -e           # All logs, errors only
sudo bash logs.sh --nginx            # Nginx error log only
sudo bash logs.sh -f -s "license"    # Follow logs filtered by "license"

Log Sources

• --service (default) — systemd journal for the nexuspanel service
• --nginx — /var/log/nginx/error.log + access.log
• --install — /opt/nexuspanel/.install.log
• --all — All sources combined

Filter Options

• -e, --errors — Only show errors, warnings, failures
• -t, --today — Only today's entries
• -s "text" — Custom regex/text filter

3. Error Checklist — errors.sh

Scans your installation for 15 common problems and prints the exact commands to fix each one. No interactivity — just diagnosis and solutions.

sudo bash errors.sh

Categories Checked

• Connection — Port listening, nginx running, nginx syntax, firewall rules, license server connectivity, DNS resolution
• Application — Node.js v18+, npm dependencies, .env configuration, data/ directory permissions, systemd service file
• Performance — Memory usage <90%, disk usage <90%, node process memory <1GB
• License & Auth — License key validity via nxl.xus.me, JWT_SECRET configuration
• Recent Logs — Error/warning count in journalctl (last 50 lines)

Example Output

━━━ Connection Errors ━━━

  ✓ Port is listening — OK
  ✓ nginx is running — OK
  ✗ nginx config is valid
    Fix: Check /etc/nginx/conf.d/nexuspanel.conf

  ✓ Firewall allows HTTP/HTTPS — OK

  ✗ 1 issue(s) found — review fixes above

4. Health Monitor — health.sh

Designed for continuous monitoring via cron. Checks 9 health metrics every run, auto-recovers from common failures, and optionally sends email alerts.

sudo bash health.sh

Cron Setup

# Run every 5 minutes:
crontab -e
# Add this line:
*/5 * * * * /opt/nexuspanel/health.sh

What It Monitors

• Service alive — Auto-restarts nexuspanel if stopped
• Port listening — Alerts if panel port is down
• Memory — Warns at 85%, auto-restarts at 95% to clear leaks
• Disk — Warns at 85%, alerts at 95%
• License server — Logs warning if nxl.xus.me unreachable (24h grace period still active)
• Nginx — Auto-restarts if stopped
• Node memory leak — Warns if node process exceeds 1GB RSS
• Log rotation — Rotates health log at 1MB, vacuums journal at 500MB
• Email alerts — Sends email on critical issues if ADMIN_EMAIL is set in .env

Email Alerts

Add ADMIN_EMAIL=you@example.com to your .env file. Ensure the mail command is installed and configured on your server.

5. Update — update.sh

Updates NexusPanel to the latest version from GitHub.

sudo bash update.sh

Steps

1. Pulls latest code from GitHub (with force-reset fallback if stash/pull fails)
2. Runs npm install --production
3. Restarts the nexuspanel service
4. Shows before/after commit hashes

6. Uninstall — uninstall.sh

Completely removes NexusPanel from your system. Requires typing DELETE to confirm.

sudo bash uninstall.sh

What It Removes

• systemd service (nexuspanel)
• Application files (/opt/nexuspanel)
• Nginx configuration (nexuspanel.conf)
• Optionally: SSL certificate for the configured domain
• Firewall rules for the app port

What It Keeps

• System packages (Node.js, nginx, certbot, Docker, PostgreSQL, ClamAV)
• Other nginx configurations
• Other applications and data

Log File Locations