wol/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

See README.md for complete project description, installation instructions, and usage details.

This is a Wake-on-LAN (WOL) Manager - a containerized Flask web application for managing and remotely waking computers on a local network.

Architecture & Code Structure

• Backend: Flask web application (app/app.py) with RESTful API endpoints
• Frontend: Single-page application with vanilla JavaScript (app/templates/index.html)
• Storage: File-based configuration in /data/wol-computers.conf
• Deployment: Docker with docker compose, requires privileged networking

Key Components

• WOLManager class in app/app.py: Core logic for computer management, WOL operations, and network scanning
• Configuration format: name|mac|ip (pipe-separated values in /data/wol-computers.conf)
• Dependencies: wakeonlan, nmap, ping, arp system tools
• Windows PowerShell scanner: scripts/windows-network-scan.ps1 - optimized network scanning from Windows host

Development Commands

For installation and basic usage, see README.md

Docker Development

Note: When running from WSL with Docker Desktop on Windows, use docker.exe compose:

# Development build and run
docker compose up -d --build
# From WSL: docker.exe compose up -d --build

# View real-time logs  
docker compose logs -f wol-web
# From WSL: docker.exe compose logs -f wol-web

# Shell access to container
docker compose exec wol-web bash
# From WSL: docker.exe compose exec wol-web bash

# Stop containers
docker compose down
# From WSL: docker.exe compose down

Network Requirements

• Runs on port 5000 (configurable via WOL_EXTERNAL_PORT env var)
• Requires NET_ADMIN and NET_RAW capabilities
• Uses network_mode: host for WOL packet transmission
• Must run with privileged: true for network operations

Network Scanning

Two scanning modes available:

1. Container-based scanning (Limited)

• Uses Linux tools: arp, ping, nmap
• Limited in Docker Desktop Windows environment
• Fallback method when Windows scanning unavailable

2. Windows PowerShell scanning (Recommended)

• Script: scripts/windows-network-scan.ps1
• Features:
  • Automatic local network detection
  • Interactive network selection menu
  • Parallel ping sweeps with configurable batch sizes
  • Hostname resolution via DNS
  • MAC address retrieval from ARP table/NetNeighbor
  • Real-time progress indication
  • Results saved to /data/network-scan-results.json

Usage patterns:

# Interactive mode with network selection menu
scripts\windows-network-scan.ps1

# Direct network specification
scripts\windows-network-scan.ps1 -Network "192.168.1.0/24"

# Advanced options
scripts\windows-network-scan.ps1 -Network "192.168.100.0/24" -TimeoutMs 500 -BatchSize 20 -Verbose

Integration:

• Web app automatically reads Windows scan results from JSON file
• Results cached for 30 minutes
• App falls back to Linux scanning if Windows results unavailable

API Endpoints

• GET /api/computers - List configured computers with status
• POST /api/wake - Wake specific computer ({mac, name, ip})
• POST /api/wake-all - Wake all configured computers
• POST /api/add - Add new computer ({name, mac, ip})
• GET /api/scan - Network scan for devices (tries Windows results first, then Linux fallback)
• POST /api/scan/windows - Trigger Windows PowerShell scan (attempts automatic execution)

Development Notes

• Application uses Romanian language in UI
• No authentication/authorization implemented
• Configuration persisted in volume-mounted /data directory
• Flask runs in debug=False mode in container

Windows Integration Details

File Integration:

• Windows scan results: /data/network-scan-results.json
• Results format: {success, timestamp, networks_scanned, computers[], message}
• Computer format: {ip, mac, hostname, status}
• Results expire after 30 minutes

WSL Integration:

• App attempts automatic PowerShell execution via WSL interop
• Path: /mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe
• Fallback: Manual execution instructions provided when auto-execution fails

Scanning Logic in app.py:

• scan_network() - Main entry point, tries Windows results first (app/app.py:164)
• try_read_windows_scan_results() - Reads and validates Windows JSON results (app/app.py:176)
• scan_network_linux() - Fallback Linux scanning using ARP/ping (app/app.py:236)
• Network filtering supported for custom CIDR ranges