TROUBLESHOOTING_WEB_INTERFACE.md

Troubleshooting Web Interface Issues

This guide helps you diagnose and fix common web interface issues with LightNVR.

Blank Page Issue

Symptoms

• Browser shows a blank white page
• Page title shows "WebRTC View - LightNVR" but no content
• No error messages visible on the page

Most Common Cause

The web assets (HTML, CSS, JavaScript files) were not installed to the web root directory during installation.

Docker vs Native Installation

Important: The troubleshooting steps differ depending on how you installed LightNVR.

For Docker Users

If you're running LightNVR in Docker, the web assets are already built into the Docker image. If you're experiencing web interface issues:

1. Check if you mounted /var/lib/lightnvr directly (this overwrites the built-in web assets):

   docker inspect lightnvr | grep -A 5 Mounts

   If you see /var/lib/lightnvr mounted, this is the problem. You should only mount /var/lib/lightnvr/data.

2. Fix the volume mount:

   # Stop the container
   docker compose down
   
   # Edit docker-compose.yml to change:
   #   - ./data:/var/lib/lightnvr        # WRONG - overwrites web assets
   # to:
   #   - ./data:/var/lib/lightnvr/data   # CORRECT - preserves web assets
   
   # Restart the container
   docker compose up -d

3. If the issue persists, recreate the container:

   docker compose down
   docker compose pull  # Get the latest image
   docker compose up -d

Note: The install_web_assets.sh script is not available in Docker containers and is not needed. The Docker image already contains all web assets.

For Native Installation Users

If you installed LightNVR directly on your system (not using Docker), use the following steps:

Quick Diagnosis

Run the diagnostic script:

sudo bash scripts/diagnose_web_issue.sh

This will check:

• Service status
• Configuration file
• Web root directory existence
• Critical web files
• Assets directory
• Recent logs

Quick Fix

If the diagnostic confirms missing web assets, run:

sudo bash scripts/install_web_assets.sh

This script will:

1. Build web assets if needed (requires Node.js/npm)
2. Install them to the correct location
3. Set proper permissions
4. Verify the installation

Then restart the service:

sudo systemctl restart lightnvr

Manual Fix (Native Installation)

If you prefer to fix it manually instead of using the script:

Option 1: Install from prebuilt assets (if available)

# Navigate to LightNVR source directory
cd /path/to/lightnvr

# Copy prebuilt assets
sudo mkdir -p /var/lib/lightnvr/www
sudo cp -r web/dist/* /var/lib/lightnvr/www/

# Set permissions
sudo chown -R root:root /var/lib/lightnvr/www
sudo chmod -R 755 /var/lib/lightnvr/www

# Restart service
sudo systemctl restart lightnvr

Option 2: Build and install from source

# Navigate to LightNVR source directory
cd /path/to/lightnvr

# Install Node.js and npm if not already installed
# On Debian/Ubuntu:
sudo apt-get update
sudo apt-get install -y nodejs npm

# Build web assets
cd web
npm install
npm run build

# Install to web root
sudo mkdir -p /var/lib/lightnvr/www
sudo cp -r dist/* /var/lib/lightnvr/www/

# Set permissions
sudo chown -R root:root /var/lib/lightnvr/www
sudo chmod -R 755 /var/lib/lightnvr/www

# Restart service
cd ..
sudo systemctl restart lightnvr

Verification

After applying the fix, verify the installation:

1. Check that files exist:

ls -la /var/lib/lightnvr/www/

You should see:

• index.html
• login.html
• streams.html
• recordings.html
• assets/ directory with CSS and JS files

2. Check service status:

sudo systemctl status lightnvr

3. Check logs for errors:

sudo tail -f /var/log/lightnvr/lightnvr.log

4. Access the web interface:

http://your-server-ip:8080

Default credentials:

• Username: admin
• Password: admin

Other Common Issues

Issue: 404 Not Found

Cause: Web root path is incorrect in configuration

Fix:

1. Check configuration:

sudo cat /etc/lightnvr/lightnvr.ini | grep "root"

2. Verify the path exists and contains files:

ls -la /var/lib/lightnvr/www/

3. If path is different, either:
   • Update config to point to correct path, OR
   • Install web assets to the configured path

Issue: Permission Denied

Cause: Incorrect file permissions

Fix:

sudo chown -R root:root /var/lib/lightnvr/www
sudo chmod -R 755 /var/lib/lightnvr/www
sudo find /var/lib/lightnvr/www -type f -exec chmod 644 {} \;
sudo systemctl restart lightnvr

Issue: JavaScript Errors in Browser Console

Symptoms: Browser console (F12) shows errors like "Failed to load module" or "404 for assets"

Cause: Incomplete or corrupted web assets

Fix for Docker:

# Recreate the container with fresh assets
docker compose down
docker compose pull
docker compose up -d

Fix for Native Installation:

1. Clear browser cache
2. Reinstall web assets:

sudo bash scripts/install_web_assets.sh
sudo systemctl restart lightnvr

Issue: Cannot Connect to Server

Symptoms: Browser shows "Connection refused" or "Unable to connect"

Possible Causes:

1. Service not running
2. Firewall blocking port
3. Wrong IP address or port

Fix:

1. Check service status:

sudo systemctl status lightnvr

2. Check if port is listening:

sudo netstat -tlnp | grep 8080
# or
sudo ss -tlnp | grep 8080

3. Check firewall (if using ufw):

sudo ufw status
sudo ufw allow 8080/tcp

4. Check firewall (if using firewalld):

sudo firewall-cmd --list-all
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload

5. Verify configuration:

sudo cat /etc/lightnvr/lightnvr.ini | grep "port"

Issue: Login Page Doesn't Work

Symptoms: Login page loads but credentials don't work

Fix:

1. Check default credentials in config:

sudo cat /etc/lightnvr/lightnvr.ini | grep -A 2 "\[web\]"

2. Try default credentials:

   • Username: admin
   • Password: admin

3. If you changed the password and forgot it, reset in config:

sudo nano /etc/lightnvr/lightnvr.ini

Change the password line under [web] section, then:

sudo systemctl restart lightnvr

Getting More Help

If none of these solutions work:

1. Collect diagnostic information:

   For Docker:

   # Collect container logs
   docker compose logs lightnvr > container_logs.txt
   
   # Check volume mounts
   docker inspect lightnvr | grep -A 10 Mounts > volume_info.txt
   
   # Check browser console
   # Open browser, press F12, go to Console tab, copy any errors

   For Native Installation:

   # Collect logs
   sudo journalctl -u lightnvr -n 100 --no-pager > service_logs.txt
   sudo tail -n 100 /var/log/lightnvr/lightnvr.log > app_logs.txt 2>/dev/null || true
   
   # Check browser console
   # Open browser, press F12, go to Console tab, copy any errors

2. Create an issue on GitHub with:

   • Installation method (Docker or native)
   • Container/service logs
   • Application logs (if applicable)
   • Browser console errors (if any)
   • Your OS and version
   • Docker version (if using Docker)

Prevention

To avoid web interface issues in future installations:

For Docker Users

1. Always use the correct volume mounts:

   • Mount /var/lib/lightnvr/data for persistent data
   • Do NOT mount /var/lib/lightnvr directly (overwrites web assets)

2. Use the official Docker image:

   docker compose pull
   docker compose up -d

3. Keep your docker-compose.yml updated: Follow the example in the repository to ensure correct configuration.

For Native Installation Users

1. Always build web assets before installation:

   cd web
   npm install
   npm run build
   cd ..

2. Use the installation script:

   sudo bash scripts/install.sh

   The install script will automatically detect and install prebuilt assets.

3. Keep backups: The install_web_assets.sh script automatically creates backups before overwriting files.