Skip to content

INSTALLATION.md

Latest commit

 

History

History
356 lines (273 loc) · 8.09 KB

INSTALLATION.md

File metadata and controls

356 lines (273 loc) · 8.09 KB

Installation & Setup Guides

Quick Links

Docker Compose (Recommended)

Prerequisites

  • Docker & Docker Compose installed (Download)
  • ~300 MB disk space

Important: Host Network Mode

⚠️ LANdalf uses Docker's host network mode to enable Wake-on-LAN functionality. Magic packets (UDP broadcasts) require access to the host network to reach devices on your local network.

What this means:

  • The application uses your host machine's network directly
  • No port mapping needed (ports 5000 and 8080 are used directly)
  • WoL magic packets are properly broadcast on your network
  • Ports 5000 and 8080 must be available on your host

Platform Support:

  • Linux: ✅ Full support - host network mode works natively
  • Windows/macOS: ⚠️ Requires Docker Desktop 4.34+ with host networking enabled (opt-in feature). See Docker Docs for setup.

Enabling Host Networking on Docker Desktop (Windows/macOS):

  1. Sign in to your Docker account in Docker Desktop
  2. Navigate to Settings
  3. Under the Resources tab, select Network
  4. Check Enable host networking
  5. Select Apply and restart

⚠️ Docker Desktop Limitations (Windows/macOS):

  • Host networking works at Layer 4 (TCP/UDP) only
  • Containers cannot bind to host IP addresses directly
  • WoL broadcasts go to the Docker VM's internal network by default — you must set WOL_BROADCASTS to your real LAN broadcast address (see below)
  • If WoL doesn't work, use Manual Setup instead

🔧 WoL on Docker Desktop (Windows/macOS): Add WOL_BROADCASTS=<your-LAN-broadcast> to the API service's environment in docker-compose.yaml. For example, if your network is 192.168.178.0/24, add WOL_BROADCASTS=192.168.178.255. Without this, magic packets are sent to the Docker VM's internal network and will not reach your devices. See the WoL Setup Guide for details.

One-Command Setup

# Clone and run
git clone https://github.com/renedierking/LANdalf.git
cd LANdalf
docker compose up -d

Verify Installation

# Check running containers
docker compose ps

# Should show:
# NAME                   STATUS
# api                    Up 2 minutes
# ui                     Up 2 minutes

Access the Application

Port Requirements

LANdalf requires the following ports on your host:

  • 5000/TCP - API server (HTTP)
  • 8080/TCP - UI server (HTTP)

If these ports are already in use, you'll need to use manual setup instead.

Stopping & Cleanup

# Stop containers
docker compose down

# Remove data
docker compose down -v

Manual Setup

Prerequisites

Step 1: Clone Repository

git clone https://github.com/renedierking/LANdalf.git
cd LANdalf

Step 2: Build Project

dotnet build LANdalf.slnx

Step 3: Run Tests (Optional)

dotnet test

Step 4: Start API (Terminal 1)

# PowerShell
cd src/API
dotnet run

# Or from root:
dotnet run --project src/API/API.csproj

Expected output:

...
Now listening on: http://localhost:5215
Now listening on: https://localhost:7206

Step 5: Start UI (Terminal 2)

# PowerShell
cd src/UI
dotnet run

# Or from root:
dotnet run --project src/UI/UI.csproj

Expected output:

...
Now listening on: http://localhost:5245
Now listening on: https://localhost:7052

Step 6: Open in Browser

Configuration

API Configuration

Environment Variables

# Linux/Mac
export Cors__FrontendUrl="https://your-frontend-url.com"

# PowerShell
$env:Cors__FrontendUrl="https://your-frontend-url.com"

# Docker (via docker-compose.yaml)
environment:
  - Cors__FrontendUrl=https://localhost:7052

Database

  • Type: SQLite
  • Location: LANdalf_Data/landalf.db
  • Auto-created: Yes, on first run
  • Migrations: Applied automatically on startup

UI Configuration

Static Configuration (src/UI/wwwroot/appsettings.json)

{
  "ApiBaseAddress": "https://localhost:7206"
}

Troubleshooting

Docker Issues

Problem: Port Already in Use

Error: bind: address already in use

Solution: Change ports in docker-compose.yaml

services:
  landalf-ui:
    ports:
      - "8081:80"  # Changed from 8080
  landalf-api:
    ports:
      - "5001:8080"  # Changed from 5000

Problem: Containers Won't Start

# Check logs
docker compose logs landalf-api
docker compose logs landalf-ui

# Full rebuild
docker compose down -v
docker compose up -d --build

Problem: Database Locked

# SQLite can lock if multiple processes access it
# Solution: Ensure only one container is running
docker compose ps

Manual Setup Issues

Problem: Build Fails

# Clean and rebuild
dotnet clean LANdalf.slnx
dotnet build LANdalf.slnx

Problem: Dependencies Not Found

# Restore NuGet packages
dotnet restore LANdalf.slnx
dotnet build

Problem: API Won't Start

Error: ASPNETCORE_ENVIRONMENT not set

Solution: Set environment

# PowerShell
$env:ASPNETCORE_ENVIRONMENT="Development"
dotnet run --project src/API/API.csproj

# Bash
export ASPNETCORE_ENVIRONMENT=Development
dotnet run --project src/API/API.csproj

Problem: CORS Errors

Access to XMLHttpRequest blocked by CORS policy

Solution: Ensure API and UI are on correct ports

If URLs differ, update:

  1. src/UI/wwwroot/appsettings.json with correct API URL
  2. src/API/appsettings.json with correct frontend URL

Network Issues

Problem: Cannot Add Devices

Error: Invalid MAC Address

Solution: MAC address must be in format: AA:BB:CC:DD:EE:FF or AA-BB-CC-DD-EE-FF

Problem: Devices Won't Wake

  1. Check Device BIOS

    • Enable "Wake-on-LAN" in network adapter settings
    • May be under "Power Management" or "Advanced" tab

  2. Check Network

    • Device must be on same subnet
    • Broadcast address must be correct
    • Router may block magic packets

  3. Debug WoL

    # On Linux/Mac, test with wakeonlan tool
brew install wakeonlan
wakeonlan -i 192.168.1.255 AA:BB:CC:DD:EE:FF

Platform-Specific Notes

Windows

  • ✅ Docker Desktop: UI/API supported; WoL via Docker host networking is limited/experimental (see Host Network Mode above)
  • ✅ Manual setup: Full support (recommended for reliable WoL)
  • Note: Windows Firewall may block ports—add exceptions for LANdalf services. Docker Desktop host networking is opt-in and may not reliably support WoL broadcasts.

Linux (Ubuntu/Debian)

# Install dependencies
sudo apt-get update
sudo apt-get install -y dotnet-sdk-10.0 docker.io docker-compose

# Run Docker without sudo
sudo usermod -aG docker $USER
newgrp docker

macOS

# Install via Homebrew
brew install dotnet docker docker-compose

# Start Docker Desktop for Docker support
open /Applications/Docker.app

Upgrading

Docker

# Pull latest image
docker compose pull
docker compose down
docker compose up -d

Manual Installation

git pull origin main
dotnet clean LANdalf.slnx
dotnet build LANdalf.slnx
# Restart API & UI services

Support