Remote Wake-on-LAN Server Installation (Docker + Python)

This guide explains how to install and run the remote Wake-on-LAN (WOL) server used by Turn Off PC.

This server acts as a bridge between the VPN and the local network, allowing devices outside the home network to wake computers using Wake-on-LAN.

The service is implemented as a Python HTTP server running inside a Docker container.

What this server does

The WOL server:

• Runs continuously on a Linux system (recommended: Raspberry Pi)
• Listens for HTTP requests on port 5000
• Receives a MAC address via HTTP POST
• Sends a Wake-on-LAN magic packet inside the local network
• Enables remote Wake-on-LAN when used together with a VPN (e.g. Tailscale)

Prerequisites

Before installing the remote Wake-on-LAN server, make sure the following components are already installed and working on the host device:

• Raspberry Pi OS (or another supported Linux distribution)
  → Raspberry Pi OS Installation

• Docker (required to run the WOL server container)
  → Docker Installation on Linux

• Tailscale (required for remote access over VPN)
  → Tailscale Installation

The host device must:

• Be powered on at all times
• Be connected to the local network
• Be connected to the VPN (Tailscale)

Resulting project structure

After completing this guide, the directory structure will be:

wol-server/
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── wol_server.py

Step 1: Create the project directory

Create a directory to host the WOL server and enter it:

mkdir -p ~/wol-server
cd ~/wol-server

Step 2: Create the Python server script

Create the main Python script:

nano wol_server.py

Paste the following code:

from flask import Flask, request
import os

app = Flask(__name__)

@app.route("/wake", methods=["POST"])
def wake():
    data = request.get_json()
    mac = data.get("mac")

    if not mac:
        return "No MAC address provided", 400

    os.system(f"wakeonlan {mac}")
    return f"Magic packet sent to {mac}", 200

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)

Save and exit: Ctrl + O → Enter Ctrl + X

Step 3: Create the Python dependencies file

Create the requirements.txt file:

nano requirements.txt

Add the required dependency:

Flask==2.3.3

Save and exit: Ctrl + O → Enter Ctrl + X

Step 4: Create the Dockerfile

Create the Dockerfile:

nano Dockerfile

Paste the following content:

FROM python:3.11-slim

RUN apt-get update && \
    apt-get install -y wakeonlan && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app

COPY requirements.txt .
COPY wol_server.py .

RUN pip install --no-cache-dir -r requirements.txt

EXPOSE 5000

CMD ["python3", "wol_server.py"]

Save and exit: Ctrl + O → Enter Ctrl + X

Step 5: Create the Docker Compose file

Using Docker Compose simplifies management and ensures the container restarts automatically.

Create the file:

nano docker-compose.yml

Paste the following configuration:

version: "3"

services:
  wol-server:
    build: .
    network_mode: "host"        # Uses the host network (required for broadcast)
    cap_add:
      - NET_ADMIN               # Allows sending broadcast packets
    restart: unless-stopped

Save and exit: Ctrl + O → Enter Ctrl + X

Why network_mode: host is required Wake-on-LAN uses broadcast packets.

Docker’s default bridge networking cannot broadcast packets correctly. Using host networking allows the container to:

Access the physical network directly

Send WOL packets to the local LAN

Behave like a native service

Step 6: Build and start the container

From inside the wol-server directory, run:

docker compose up -d

Docker will:

Build the image

Install dependencies

Start the server in the background

Step 7: Verify that the server is running

Check running containers:

docker ps

You should see output similar to:

CONTAINER ID   IMAGE                   COMMAND                  CREATED         STATUS         PORTS     NAMES
4XXXXXX31ba4   wol-server-wol-server   "python3 wol_server.py"  4 minutes ago   Up 4 minutes             wol-server-wol-server-1

If the container is running, the server is active.

How the server is used The server listens on:

http://<SERVER_IP>:5000/wake It expects an HTTP POST request with JSON data:

{
  "mac": "AA:BB:CC:DD:EE:FF"
}

Step 8: Enable Remote WOL in Turn Off PC (mobile app)

Open Turn Off PC on your phone

Go to edit your device

Enable Remote WOL

Enter the raspberry IP in the external server IP

Save the configuration

That’s all. Remote Wake-on-LAN is now enabled.