https://github.com/cyrof/remotewakeserver
This project provides a Wake-on-LAN (WoL) HTTP server with two scripts: main.py to send WoL packets and server.py to handle HTTP requests. The server can be deployed using Docker, with environment variables for the MAC address and broadcast IP specified in the Docker run command or Docker Compose. Ideal for remote server management.
https://github.com/cyrof/remotewakeserver
docker python wake-on-lan
Last synced: 23 days ago
JSON representation
This project provides a Wake-on-LAN (WoL) HTTP server with two scripts: main.py to send WoL packets and server.py to handle HTTP requests. The server can be deployed using Docker, with environment variables for the MAC address and broadcast IP specified in the Docker run command or Docker Compose. Ideal for remote server management.
- Host: GitHub
- URL: https://github.com/cyrof/remotewakeserver
- Owner: Cyrof
- License: mit
- Created: 2024-05-23T16:19:32.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-27T14:59:04.000Z (about 2 years ago)
- Last Synced: 2025-01-21T11:45:09.920Z (over 1 year ago)
- Topics: docker, python, wake-on-lan
- Language: Python
- Homepage:
- Size: 7.81 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Wake-on-LAN HTTP Server
A lightweight Wake-on-Lan (WoL) HTTP API and web UI, designed for homelab and Kubernetes (k3s) environments.
It allows you to securely send WoL magic packet via:
- a simple web UI (button click)
- HTTP API requests
Typical use case:
> VPN into home -> open internal URL -> click "Wake PC" -> RDP / Parsec in
## Features
- FastAPI-based HTTP API
- Simple built-in web UI
- Token-based authentication (optional but recommended)
- Multiple devices support (by name or MAC)
- Docker & Kubernetes friendly
- Multi-arch images (amd64 / arm64)
- Works great behind VPN (WireGuard / Pi-hole DNS)
## How It Works
1. Client sends an HTTP request (or clicks a button)
2. Server validates an optional auth token
3. Server sends a Wake-on-LAN magic packet via UDP broadcast
4. Target machine powers on
> For best reliability in Kubernetes, run this service with `hostNetwork: true` so broadcast packets reach you LAN correctly.
## Configuration
All configuration is done via environment variables.
### Required / Common Variables
| Variable | Description | Example |
| --------------- | -------------------------------- | ---------------- |
| `WOL_BROADCAST` | Broadcast IP for your LAN | `192.168.68.255` |
| `WOL_PORT` | UDP port for WoL (default: 9) | `9` |
| `WOL_TOKEN` | Optional auth token | `supersecret` |
| `WOL_DEVICES` | JSON map of device names to MACs | see below |
### Example `WOL_DEVICES`
```json
{
"pc": {
"mac": "AA:BB:CC:DD:EE:FF"
},
"nas": {
"mac": "11:22:33:44:55:66"
}
}
```
## Running with Docker
### Pull the image
```sh
docker pull cyrof/remotewakeserver:latest
```
## Run the container
```sh
docker run -d \
-p 8000:8000 \
-e WOL_BROADCAST=192.168.68.255 \
-e WOL_TOKEN=supersecret \
-e WOL_DEVICES='{"pc":{"mac":"AA:BB:CC:DD:EE:FF"}}' \
cyrof/remotewakeserver:latest
```
Then open:
```arduino
http://localhost:8000
```
## API Usage
### Health Check
```sh
curl http://localhost:8000/healthz
```
Response:
```json
{ "ok": true }
```
### List Devices
```sh
curl -H "X-Auth-Token: supersecret" \
http://localhsot:8000/api/devices
```
Response:
```json
["pc", "nas"]
```
### Wake a Device by Name
```sh
curl -X POST http://localhost:8000/api/wake \
-H "Content-Type: application/json" \
-H "X-Auth-Token: supersecret" \
-d '{"name":"pc"}'
```
### Wake a Device by MAC
```sh
curl -X POST http://localhost:8000/api/wake \
-H "Content-Type: application/json" \
-H "X-Auth-Token: supersecret" \
-d '{"mac":"AA:BB:CC:DD:EE:FF"}'
```
## Web UI
Visiting `/` serves a simple HTML page with:
- Token input
- One "Wake" button per configured device
Perfect for phone / tablet usage over VPN.
## Kubernetes / k3s Notes
Recommended settings:
- Run with `hostNetwork: true`
- Expose via ingress or internal Service
- Store `WOL_TOKEN` in a Secret
- Map a friendly domain via Pi-hole DNS (e.g., `wol.home.arpa`)
## Project Structure
```text
.
├── app
│ ├── api.py
│ ├── __init__.py
│ ├── settings.py
│ └── wol.py
├── Dockerfile
├── LICENSE
├── pyproject.toml
├── README.md
└── uv.lock
```
## Development
### Local run (with uv)
```sh
uv sync
uv run uvicorn app.api:app --host 0.0.0.0 --port 8000
```
## Security Notes
- Designed for internal / VPN use
- Token auth prevent accidental or unauthorised wake requests
- No public exposure recommended
## Contributing
Feel free to contribute to this project by forking this reopsitory and creating a pull request with your changes.
## Issues
If you encounter any issues of have suggestions for improvements, please open an issue in the repository
## License
This project is licensed under the [MIT license](https://github.com/Cyrof/RemoteWakeServer/blob/main/LICENSE).