Guardian Eye on Linux: Complete Installation Guide

Introduction

Guardian Eye runs natively on Linux, providing the same powerful video surveillance features you'd expect on Windows - but with the stability, security, and performance advantages of Linux.

This guide covers everything you need to install Guardian Eye on popular Linux distributions, configure cameras, and get your surveillance system running smoothly.

Why Choose Linux for Surveillance?

• Rock-solid stability - Linux servers can run for months/years without rebooting
• Better performance - Lower resource usage means more cameras on same hardware
• Free and open-source - No licensing costs for the operating system
• Remote access built-in - SSH for easy headless server management
• Advanced automation - systemd services, cron jobs, custom scripts
• Perfect for NAS/server setups - Run on existing home server infrastructure

System Requirements

Minimum Requirements

Supported Distributions

• Ubuntu - 20.04 LTS, 22.04 LTS, 24.04 LTS (recommended for beginners)
• Debian - 11 (Bullseye), 12 (Bookworm)
• Fedora - 38, 39, 40
• Arch Linux - Rolling release (advanced users)
• Other - Any distribution with .NET 8.0 runtime support

Note: Guardian Eye is built on .NET 8.0, which supports most modern Linux distributions. If your distribution isn't listed, check if it can run .NET 8.0 applications.

Installation Methods

Method 1: DEB Package (Ubuntu/Debian)

Easiest method for Debian-based distributions with automatic dependency resolution.

1. Download the .deb package:
   wget https://getguardianeye.com/downloads/linux/GuardianEye-1.0.0-linux-x64.deb
2. Install with apt:
   sudo apt install ./GuardianEye-1.0.0-linux-x64.deb

   This automatically installs .NET runtime and other dependencies.

3. Verify installation:
   guardianeye --version

   Should output: Guardian Eye v1.0.0

4. Start the service:
   sudo systemctl start guardianeye
   sudo systemctl enable guardianeye # Auto-start on boot

Method 2: Tarball (Any Distribution)

Manual installation for Fedora, Arch, or other non-Debian distributions.

1. Install .NET 8.0 Runtime:
   # Ubuntu/Debian
   sudo apt install dotnet-runtime-8.0
   
   # Fedora
   sudo dnf install dotnet-runtime-8.0
   
   # Arch
   sudo pacman -S dotnet-runtime-8.0
2. Download and extract tarball:
   wget https://getguardianeye.com/downloads/linux/GuardianEye-1.0.0-linux-x64.tar.gz
   sudo mkdir -p /opt/guardianeye
   sudo tar -xzf GuardianEye-1.0.0-linux-x64.tar.gz -C /opt/guardianeye
3. Set permissions:
   sudo chmod +x /opt/guardianeye/GuardianEye
   sudo chown -R $USER:$USER /opt/guardianeye
4. Create symbolic link (optional):
   sudo ln -s /opt/guardianeye/GuardianEye /usr/local/bin/guardianeye
5. Run Guardian Eye:
   /opt/guardianeye/GuardianEye

Method 3: Build from Source (Advanced)

For developers or users who want the latest development version.

1. Install .NET SDK:
   sudo apt install dotnet-sdk-8.0 # Ubuntu/Debian
2. Clone repository:
   git clone https://github.com/homeprimus-pa/Guardian.Eye.git
   cd Guardian.Eye
3. Build project:
   dotnet build -c Release
   dotnet publish -c Release -r linux-x64 --self-contained false
4. Run from bin folder:
   ./bin/Release/net8.0/linux-x64/publish/GuardianEye

Setting Up systemd Service (Autostart)

Make Guardian Eye start automatically on boot using systemd.

1. Create service file:
   sudo nano /etc/systemd/system/guardianeye.service
2. Add service configuration:
   [Unit]
   Description=Guardian Eye Surveillance System
   After=network.target
   
   [Service]
   Type=notify
   User=guardianeye
   WorkingDirectory=/opt/guardianeye
   ExecStart=/opt/guardianeye/GuardianEye
   Restart=on-failure
   RestartSec=10
   
   [Install]
   WantedBy=multi-user.target
3. Create dedicated user (security best practice):
   sudo useradd -r -s /bin/false guardianeye
   sudo chown -R guardianeye:guardianeye /opt/guardianeye
4. Enable and start service:
   sudo systemctl daemon-reload
   sudo systemctl enable guardianeye
   sudo systemctl start guardianeye
5. Check service status:
   sudo systemctl status guardianeye

Accessing Guardian Eye

GUI Access (Desktop Environments)

If you're running a desktop Linux distribution (Ubuntu Desktop, Linux Mint, etc.):

1. Launch from application menu: Applications → Multimedia → Guardian Eye
2. Or run from terminal: guardianeye
3. Configure cameras from Settings → Cameras menu

Web Interface Access (Headless Servers)

For servers without GUI, Guardian Eye provides a web interface:

1. Guardian Eye runs web server on http://localhost:5000 by default
2. Access from another computer: http://server-ip:5000
3. Configure firewall to allow port 5000:
   sudo ufw allow 5000/tcp # UFW (Ubuntu)
   sudo firewall-cmd --add-port=5000/tcp --permanent # firewalld (Fedora)
4. For production, set up reverse proxy (nginx) with HTTPS

Configuring Cameras on Linux

USB Webcam Detection

Guardian Eye uses V4L2 (Video4Linux2) for USB webcams.

1. List available webcams:
   v4l2-ctl --list-devices
2. Check device permissions:
   ls -l /dev/video*

   Add your user to video group:

   sudo usermod -aG video $USER
   # Log out and back in for changes to apply
3. In Guardian Eye: Settings → Cameras → Add Camera → USB Webcam → Select /dev/video0

IP Camera (RTSP) Setup

Same as Windows - Guardian Eye uses standard RTSP protocol.

Network Tip: Ensure your Linux server and cameras are on same network/VLAN. Test connectivity: ping 192.168.1.100

Storage Configuration

Dedicated Recording Drive

Best practice: Use separate HDD/SSD for recordings.

1. Mount drive permanently:
   sudo mkdir -p /mnt/surveillance
   sudo blkid # Find UUID of your drive
   sudo nano /etc/fstab
   
   # Add line (replace UUID with your drive's UUID):
   UUID=YOUR-UUID-HERE /mnt/surveillance ext4 defaults 0 2
   
   sudo mount -a
2. Set permissions:
   sudo chown -R guardianeye:guardianeye /mnt/surveillance
   sudo chmod 755 /mnt/surveillance
3. Configure in Guardian Eye: Settings → Recording → Output Path → /mnt/surveillance/recordings

Automatic Old Recording Cleanup

Guardian Eye auto-deletes old recordings based on retention settings, but you can also use systemd timer:

Common Issues & Troubleshooting

❌ Problem: "GuardianEye: command not found"

Solutions:

• Ensure PATH includes installation directory: echo $PATH
• Create symlink: sudo ln -s /opt/guardianeye/GuardianEye /usr/local/bin/guardianeye
• Run directly: /opt/guardianeye/GuardianEye

❌ Problem: USB Webcam not detected

Solutions:

• Check if device is recognized: lsusb and v4l2-ctl --list-devices
• Install v4l-utils: sudo apt install v4l-utils
• Add user to video group: sudo usermod -aG video $USER (logout/login required)
• Check permissions: ls -l /dev/video0 (should show crw-rw----+ 1 root video)

❌ Problem: High CPU/Memory usage

Solutions:

• Reduce camera resolution/FPS in camera settings
• Use H.264 hardware acceleration if available:
  # Check for hardware encoding support
  ffmpeg -hwaccels
  
  # Enable in Guardian Eye: Settings → Advanced → Use Hardware Acceleration
• Monitor resources: htop or systemctl status guardianeye
• Disable motion detection zones if not needed

❌ Problem: Service fails to start

Solutions:

• Check logs: sudo journalctl -u guardianeye -n 50 --no-pager
• Verify .NET runtime: dotnet --list-runtimes (should show 8.0.x)
• Check file permissions: ls -l /opt/guardianeye
• Test manual start: sudo -u guardianeye /opt/guardianeye/GuardianEye

❌ Problem: Cannot access web interface from network

Solutions:

• Check firewall: sudo ufw status or sudo firewall-cmd --list-all
• Allow port 5000:
  sudo ufw allow 5000/tcp
• Verify service is listening: sudo netstat -tlnp | grep 5000
• Test locally first: curl http://localhost:5000

Performance Optimization Tips

1. Use SSD for OS and Database

Install Guardian Eye on SSD for faster startup and database operations. Use HDD for recordings only.

2. Adjust swappiness (Servers with limited RAM)

3. Disable GUI on Servers

Save resources by running headless:

4. Use Lower Motion Detection Sensitivity

Reduce false positives and CPU usage: Settings → Motion Detection → Sensitivity: Medium (instead of High)

5. Limit Recording FPS

15 FPS is sufficient for most surveillance needs (vs 30 FPS default).

Security Best Practices

• Run as non-root user - Always use dedicated guardianeye user (shown in systemd setup)
• Firewall configuration - Only allow port 5000 from trusted IPs
• Use reverse proxy with HTTPS - Set up nginx with Let's Encrypt SSL for remote access
• Isolate cameras in VLAN - Prevent cameras from accessing internet or main network
• Regular updates - Keep Guardian Eye and system packages updated
• Secure recording storage - Encrypt recording drive if dealing with sensitive footage

Conclusion

Guardian Eye on Linux provides a powerful, flexible, and cost-effective surveillance solution. Whether you're running a home server, NAS, or dedicated security system, Linux's stability and performance make it an excellent choice for 24/7 recording.

Quick recap:

1. Install via .deb package (Ubuntu/Debian) or tarball (other distributions)
2. Set up systemd service for autostart
3. Configure USB webcams via V4L2 or RTSP IP cameras
4. Use dedicated drive for recordings with proper permissions
5. Access via GUI (desktop) or web interface (headless servers)
6. Optimize performance: hardware acceleration, lower FPS, swappiness tuning
7. Secure: non-root user, firewall, HTTPS reverse proxy