kotsiossp97/powerbeacon repository overview

⁠PowerBeacon

A Centralized Wake-on-LAN (WoL) Orchestration Platform

GitHub Repository⁠ | Report an Issue⁠ | Documentation⁠

⁠🚀 Overview

PowerBeacon is a modern, distributed Wake-on-LAN orchestration platform. It is designed to help you easily manage, wake, and monitor devices across multiple isolated networks from a single, centralized control plane.

Traditional Wake-on-LAN is limited to the local broadcast domain (Layer 2). PowerBeacon solves this by using a central server (Control Plane) and lightweight remote agents (Execution Plane) deployed on your target networks to dispatch the "magic packets" exactly where they need to go.

⁠🌟 Key Features

• Centralized Dashboard: A clean, React-based web UI to manage all your devices and networks.
• Distributed Agents: Lightweight Go-based agents that sit in remote networks to dispatch Wake-on-LAN packets locally.
• Modern API: Built on Python & FastAPI, offering a robust REST API for integrations and automation.
• Device Management: Register, group, and track the status of your machines.

⁠🐳 Quick Start

The easiest way to get the PowerBeacon control plane (Backend + Frontend) up and running is using Docker Compose.

⁠1. Using Docker Compose (Recommended)

Create a docker-compose.yml file:

services:
  db:
    image: postgres:16-alpine
    container_name: powerbeacon-db
    environment:
      POSTGRES_USER: powerbeacon
      POSTGRES_PASSWORD: ${DB_PASSWORD:-changeMe}
      POSTGRES_DB: powerbeacon
    volumes:
      - powerbeacon_data:/var/lib/postgresql/data
    networks:
      - powerbeacon_network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U powerbeacon"]
      interval: 10s
      timeout: 5s
      retries: 5

  powerbeacon:
    image: kotsiossp97/powerbeacon:latest
    container_name: powerbeacon
    environment:
      DB_URL: postgresql://powerbeacon:${DB_PASSWORD:-changeMe}@db:5432/powerbeacon
      JWT_SECRET: ${JWT_SECRET:-your-secret-key-change-in-production}
    ports:
      - "8000:80"
    depends_on:
      db:
        condition: service_healthy
    networks:
      - powerbeacon_network

volumes:
  powerbeacon_data:

networks:
  powerbeacon_network:
    driver: bridge

Then run:

docker-compose up -d

⁠2. Standard Docker Run

docker run -d \
  --name powerbeacon \
  -p 8000:80 \
  -e DB_URL=postgresql://powerbeacon:changeMe@db:5432/powerbeacon \
  -e JWT_SECRET=your-secret-key-change-in-production \
  kotsiossp97/powerbeacon:latest

⁠🔌 Deploying the Agent

To actually wake devices, you will need to deploy the PowerBeacon Agent on the same local network as the target devices. The agent connects back to this central Docker container to receive wake instructions.

You can find more information and deployment instructions in the Documentation⁠ and in the web UI once the control plane is up.

⁠🤝 Contributing & Feedback

PowerBeacon is an open-source project! We welcome contributions, bug reports, and feature requests. If you encounter any issues or want to help improve the project, please head over to our GitHub Issues page⁠.