GPTWOL Documentation

GPTWOL sends a reverse MAC Wake-on-LAN packet on port 9 to trigger a shutdown. To enable this, you must install and configure the sleep-on-lan utility on the target computer.

Debian-based computers

Create a sol.json file with the following content:

{
    "Listeners": [
        "UDP:9"
    ],
    "LogLevel": "INFO",
    "Commands": [
        {
            "Operation": "shutdown",
            "Command": "poweroff",
            "Default": true
        }
    ]
}

Windows computers

Create a sol.json file with the following content:

{
    "Listeners": [
        "UDP:9"
    ],
    "LogLevel": "INFO",
    "Commands": [
        {
            "Operation": "shutdown",
            "Command": "shutdown /s /t 0 /f",
            "Default": true
        }
    ]
}

Note for Windows: You must configure the Windows Defender Firewall to allow an Inbound Rule for UDP port 9.

In versions 4.0.0 and above, the computers.txt file is no longer mounted as a standalone file. Instead, it is stored within the /app/db directory inside the container.

If you see the warning message Computers migration needed, you must move your existing computers.txt file to the new database directory and update your docker-compose.yml configuration. Follow these steps in your docker-compose.yml root path:

# 1. Stop the current containers
docker compose down || sudo docker compose down

# 2. Create the new database directory
mkdir -p appdata/db || sudo mkdir -p appdata/db

# 3. Locate the old computers.txt path from docker-compose.yml, copy it to the new location, and update the compose file
old_computer_location=$(grep "/app/computers.txt" docker-compose.yml | awk '{print $NF}' | awk -F':' '{print $1}')
[ -f "$old_computer_location" ] && (cp "$old_computer_location" appdata/db/computers.txt || sudo cp "$old_computer_location" appdata/db/computers.txt) && (sed -i 's|-.*:/app/computers.txt|- ./appdata/db:/app/db|' docker-compose.yml || sudo sed -i 's|-.*:/app/computers.txt|- ./appdata/db:/app/db|')

# 4. Restart the containers
docker compose up -d || sudo docker compose up -d

The recommended way to deploy GPTWOL is using Docker Compose.

Important Requirements:

• The container must run in host network mode to send Wake-on-LAN packets to your local network.
• Ensure the PORT you select is free on your host machine.
• Ensure BIOS settings and the remote OS are configured to allow Wake-on-LAN.
• Do not expose GPTWOL directly to the internet without enabling authentication.

Create a docker-compose.yml file with the following configuration:

services:
  gptwol:
    container_name: gptwol
    image: misterbabou/gptwol:latest
    network_mode: host
    restart: unless-stopped
    environment:
      - TZ=Europe/Paris
      # - PORT=5000
      # - IP=0.0.0.0
      # - LOG_LEVEL=INFO
      # - ENABLE_LOGIN=false
      # - USERNAME=admin
      # - PASSWORD=admin
      # - OIDC_ENABLED=false
      # - OIDC_ISSUER=https://auth.exemple.com
      # - OIDC_CLIENT_ID=oidcclientid
      # - OIDC_CLIENT_SECRET=oidcclientsecret
      # - OIDC_REDIRECT_URI=http(s)://urlofyourgptwol(:port)
      # - SCRIPT_NAME=/my-app
      # - ENABLE_ADD_DEL=true
      # - ENABLE_REFRESH=true
      # - REFRESH_INTERVAL=30
      # - PING_TIMEOUT=300
      # - ARP_INTERFACE=eth0
      # - ARP_TIMEOUT=300
      # - TCP_TIMEOUT=1
      # - ENABLE_L2_WOL_PACKET=false
      # - L2_INTERFACE=eth0
    volumes:
      - ./appdata/db:/app/db
      - ./appdata/cron:/etc/cron.d

Then run the application with:

docker compose up -d

The following environment variables can be used to configure the GPTWOL Docker container: