WakeDash

WakeDash is a simple web dashboard for Wake-on-LAN. It is intended mainly for homelabs, small businesses, and internal networks where you want to wake a server, NAS, or workstation quickly — without Kubernetes, Redis queues, or ceremonial microservice choreography.

The application runs as a small Flask server, uses a SQLite database, and is designed for straightforward systemd deployment.

A Czech version of this README is available in README_cs.md.

Features

• Wake-on-LAN buttons for configured devices
• optional anonymous Wake mode for homelab deployments
• user accounts with user / admin roles
• device management through the web UI
• YAML import/export for device configuration
• watchdog that can monitor a device IP address and send WOL after longer downtime
• recent action history
• light/dark UI mode
• CSRF protection for mutating requests
• stable Flask session secret via file or environment variable
• simple systemd deployment

Requirements

On Debian/Ubuntu systems:

sudo apt install python3 python3-venv python3-pip wakeonlan iputils-ping

Python dependencies are listed in:

requirements.txt

Runtime dependencies:

Flask
PyYAML
Werkzeug

Quick installation with install.sh

Recommended simple installation:

sudo ./install.sh

The installer runs in an interactive, TUI-like flow. It clears the screen, keeps the WakeDash ASCII banner pinned at the top, prints the installation plan below it, and updates questions/results in a progress area under the banner. It also checks required system commands and asks before installing missing apt packages.

For unattended installation:

sudo ./install.sh --yes

The installer will:

• show the planned service name, install directory, env file and run user
• check required commands/packages
• optionally install missing system packages through apt-get
• create the wakedash system user
• create /opt/wakedash
• copy/update application files, safely skipping files that are already in place
• create a Python virtualenv in /opt/wakedash/.venv
• install Python dependencies
• create /etc/wakedash/wakedash.env if it does not exist yet
• install the systemd service
• enable and start the service

After installation:

systemctl status wakedash.service
journalctl -u wakedash.service -f

Default URL:

http://<server>:8080/

On first visit, WakeDash will prompt you to create the first admin account.

Custom installation paths

The installer supports environment overrides:

sudo INSTALL_DIR=/srv/wakedash ENV_FILE=/etc/wakedash/wakedash.env ./install.sh

Available installer variables:

SERVICE_NAME=wakedash
INSTALL_DIR=/opt/wakedash
ENV_FILE=/etc/wakedash/wakedash.env
RUN_USER=wakedash

Example:

sudo SERVICE_NAME=wakedash INSTALL_DIR=/srv/wakedash RUN_USER=wakedash ./install.sh

Configuration

The main configuration file for systemd deployments is:

/etc/wakedash/wakedash.env

The repository contains an example file:

wakedash.env.example

The example file is intentionally heavily commented and acts as inline documentation for the available values.

After changing configuration, restart the service:

sudo systemctl restart wakedash.service

Important variables

Network binding

SIMPLE_WOL_HOST=0.0.0.0
SIMPLE_WOL_PORT=8080

Port 80 is a privileged port on Linux. The bundled systemd service grants CAP_NET_BIND_SERVICE so the non-root wakedash user can bind it. The service also grants CAP_NET_RAW, because WakeDash uses ping for status checks and systemd capability bounding can otherwise make every monitored device look offline even when host-level ping works. If you use a custom service file and set SIMPLE_WOL_PORT=80 or rely on status checks, make sure it includes both capabilities.

0.0.0.0 means listening on all interfaces. If WakeDash runs only behind a reverse proxy on the same machine, you can use:

SIMPLE_WOL_HOST=127.0.0.1

Runtime paths

SIMPLE_WOL_DIR=/opt/wakedash
SIMPLE_WOL_DB=/opt/wakedash/simple-wol.db
SIMPLE_WOL_SECRET_KEY_FILE=/opt/wakedash/secret_key

The SQLite database, backups, and generated session secret are stored under SIMPLE_WOL_DIR.

Flask session secret

Recommended default mode:

SIMPLE_WOL_SECRET_KEY_FILE=/opt/wakedash/secret_key

If SIMPLE_WOL_SECRET_KEY is not set, the app creates this file on first startup with mode 0600 and reuses it across restarts. This keeps user sessions stable after service restarts.

Optionally, you can set an explicit secret:

SIMPLE_WOL_SECRET_KEY=<long-random-string>

Generate one with:

python3 -c 'import secrets; print(secrets.token_hex(32))'

HTTP vs HTTPS cookie mode

SIMPLE_WOL_COOKIE_SECURE=0

The default value 0 is suitable for plain HTTP homelab deployments.

If WakeDash is served via HTTPS or a TLS-terminating reverse proxy, set:

SIMPLE_WOL_COOKIE_SECURE=1

Do not enable this on plain HTTP. Browsers will not send Secure cookies over HTTP, so login will appear broken. It is technically very secure: not even the admin gets in. Operationally, that is less charming.

Anonymous Wake-on-LAN

SIMPLE_WOL_ALLOW_ANONYMOUS_WAKE=1

The default homelab mode allows unauthenticated visitors to send Wake-on-LAN packets.

For stricter small-business deployments, set:

SIMPLE_WOL_ALLOW_ANONYMOUS_WAKE=0

Then the Wake button/API requires login as user or admin.

Device management, user management, and watchdog controls always require login.

Watchdog intervals

SIMPLE_WOL_PING_INTERVAL=30
SIMPLE_WOL_OFFLINE_BEFORE_WOL=300
SIMPLE_WOL_RETRY_INTERVAL=60
SIMPLE_WOL_RETRY_COUNT=5
SIMPLE_WOL_WATCHDOG_RESET_AFTER=3600
SIMPLE_WOL_MAX_HISTORY_ITEMS=100

Meaning:

• SIMPLE_WOL_PING_INTERVAL — how often the watchdog checks devices
• SIMPLE_WOL_OFFLINE_BEFORE_WOL — how long a device must be offline before watchdog starts sending WOL packets
• SIMPLE_WOL_RETRY_INTERVAL — delay between repeated WOL attempts
• SIMPLE_WOL_RETRY_COUNT — maximum number of retry attempts
• SIMPLE_WOL_WATCHDOG_RESET_AFTER — offline duration after which the retry counter is reset
• SIMPLE_WOL_MAX_HISTORY_ITEMS — number of history entries kept in the database

Watchdog worker

SIMPLE_WOL_START_WORKER=1

For normal single-process systemd deployment, keep this set to 1.

WakeDash starts the watchdog as a thread inside the application process. Therefore the recommended production mode for this simple app is one process / one worker.

If you later use Gunicorn or another application server, do not run multiple workers with the watchdog enabled, otherwise the watchdog will run multiple times. That becomes a small Wake-on-LAN choir, and not the good kind.

Systemd service

Example service file:

wakedash.service.example

Default service settings:

User=wakedash
Group=wakedash
WorkingDirectory=/opt/wakedash
EnvironmentFile=-/etc/wakedash/wakedash.env
ExecStart=/opt/wakedash/.venv/bin/python /opt/wakedash/app.py

The installer generates the real service file from this example according to the selected installation paths.

Manual installation example:

sudo cp wakedash.service.example /etc/systemd/system/wakedash.service
sudo systemctl daemon-reload
sudo systemctl enable --now wakedash.service

If you use paths other than /opt/wakedash, edit the service file first.

Reverse proxy

WakeDash can run directly on a LAN over HTTP, or behind nginx/apache/caddy.

For reverse proxy deployments, configure /etc/wakedash/wakedash.env like this:

SIMPLE_WOL_HOST=127.0.0.1
SIMPLE_WOL_PORT=8080
SIMPLE_WOL_COOKIE_SECURE=1

Set SIMPLE_WOL_COOKIE_SECURE=1 only if users access WakeDash via HTTPS.

Minimal nginx example:

server {
    listen 443 ssl;
    server_name wakedash.example.local;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

TLS certificates and DNS are left to the local network administrator's preferred religion.

Manual development run

From the repository:

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements-dev.txt
SIMPLE_WOL_DIR=/tmp/wakedash-dev \
SIMPLE_WOL_DB=/tmp/wakedash-dev/simple-wol.db \
SIMPLE_WOL_START_WORKER=0 \
python app.py

Then open:

http://127.0.0.1:8080/

Note: SIMPLE_WOL_START_WORKER=0 is often more convenient during development so the watchdog does not send WOL packets during every test run.

Tests

Install development dependencies:

pip install -r requirements-dev.txt

Run tests:

pytest -q

Current tests mainly cover security and operational behavior:

• CSRF protection
• secure cookie opt-in
• environment configuration for watchdog intervals
• enabling/disabling anonymous Wake

Data and backups

WakeDash uses a SQLite database:

/opt/wakedash/simple-wol.db

When devices are changed or configuration is imported, backups are created under:

/opt/wakedash/backups/

Backup recommendations:

• back up simple-wol.db
• optionally back up the whole /opt/wakedash directory
• do not bother backing up the Python virtualenv; it can be recreated from requirements.txt

Git hygiene

The repository contains a .gitignore that excludes:

• Python caches
• virtualenvs
• .env files
• secrets/keys/certificates
• SQLite databases
• runtime backups
• logs

Do not commit:

*.db
backups/
secret_key
.env
/etc/wakedash/wakedash.env

Database backups may contain MAC addresses, internal IP addresses, users, and password hashes. In other words: exactly the things you do not want to rediscover in a repository six months later with the comment “it's only internal”.

Security notes

WakeDash is an internal tool. It is not designed to be a public internet-facing service.

Recommendations:

• run it only on trusted LAN/VPN networks
• for business deployments, consider SIMPLE_WOL_ALLOW_ANONYMOUS_WAKE=0
• for HTTPS proxy deployments, use SIMPLE_WOL_COOKIE_SECURE=1
• do not run multiple application workers with the watchdog enabled
• do not commit databases or secrets to git
• back up the SQLite database regularly

Troubleshooting

Wake does not work

Check that the wakeonlan command is installed:

command -v wakeonlan

On Debian/Ubuntu:

sudo apt install wakeonlan

Verify the MAC address, broadcast address, and whether the target device supports Wake-on-LAN.

Status is always offline

WakeDash uses ping.

Check manually:

ping -c 1 <IP-address>

Some systems or firewalls block ICMP. In that case, the device may be working, but the dashboard will show it as offline. The network is lying again, as is tradition.

Login breaks after enabling secure cookies

If you are running over plain HTTP, set:

SIMPLE_WOL_COOKIE_SECURE=0

Then restart the service:

sudo systemctl restart wakedash.service

Configuration changed but nothing happened

After changing /etc/wakedash/wakedash.env, restart the service:

sudo systemctl restart wakedash.service

Service logs

journalctl -u wakedash.service -f

License

Add the project license as needed.