Wake-On-Request

Wake-On-Request automatically puts your Docker and Podman containers to sleep when idle and wakes them up instantly when someone visits your website. It runs directly inside Nginx Proxy Manager (NPM)'s OpenResty process, requiring no sidecar containers.

Features

• Zero-UI Configuration: Configure containers entirely via Docker labels. The installer will patch your compose files automatically.
• NPM Advanced Tab Configuration: Configure containers in the NPM Web UI using simple Nginx variables.
• Global Interception: Incoming requests are intercepted globally via a single injection block. No individual proxy host needs custom Lua access blocks.
• Cross-Network Support: Fully supports containers running on different networks or using host network mode via TCP readiness probes targeted at host IPs and published ports.
• Automated Cleanup: The installer automatically scans NPM's database to detect and clean up old, deprecated inline Lua access blocks.
• Interactive CLI Installer: Scans the Docker daemon, matches container IPs/ports against NPM proxy hosts, prompts for the preferred configuration method, previews changes, and takes timestamped backups of all files before modifying them.
• Performance and Stability: Timer scheduling is non-blocking to prevent OpenResty pool exhaustion, uses bounded TTL memory keys, and handles container startup failures gracefully with a retry-capped splash screen.

Phase 1: Installation and Setup

Run these steps in the directory where your Nginx Proxy Manager compose file is located.

1. Run the Installer

Run the script to download the engine files, scan your containers, and inject the global volume mounts into your NPM service definition:

# Download the installer
curl -O https://raw.githubusercontent.com/msenturk/wake-on-request/master/install.py

# Run interactively (will prompt to configure discovered containers)
sudo python3 install.py

Advanced CLI Options:

# Target a specific NPM directory (positional or via --path)
sudo python3 install.py /path/to/nginx-proxy-manager
# or
sudo python3 install.py --path /path/to/nginx-proxy-manager

# Only configure a specific container (skips prompts for others)
sudo python3 install.py --container my-app

# Manually specify the NPM container name or ID
sudo python3 install.py --npm my-custom-npm-container

# Preview proposed changes without modifying anything
sudo python3 install.py --dry-run

2. Apply NPM Changes

Restart your NPM stack to load the Wake-On-Request OpenResty plugin. This is only required once during the initial installation.

docker compose up -d --force-recreate <npm-service-name>

Phase 2: Container Configuration

To manage a container, ensure its restart policy is set to restart: "no" (so Wake-On-Request can keep it stopped when idle) and configure it using one of the two methods below.

Method A: Docker Labels (Recommended)

Add configuration parameters directly to your application's compose file. No changes are needed in Nginx Proxy Manager.

services:
  my-app:
    image: my-app:latest
    container_name: my-app
    restart: "no"
    expose:
      - "8080"
    labels:
      - "wakeonrequest.enable=true"
      - "wakeonrequest.domain=app.example.com"
      - "wakeonrequest.idle_timeout=300"
      - "wakeonrequest.start_timeout=30"
      - "wakeonrequest.probe_host=192.168.1.103"
      - "wakeonrequest.port=8080"
    networks:
      - npm_proxy

Apply the changes by recreating the container:

docker compose up -d --force-recreate my-app

Method B: NPM Advanced Tab

If you prefer not to add labels to your container, you can configure it entirely inside Nginx Proxy Manager's Web UI.

1. Edit your Proxy Host in the NPM Admin dashboard.
2. Go to the Advanced Tab and paste the Nginx variable definitions:

set $wake_container      "my-container-name";
set $wake_idle_timeout   300;
set $wake_start_timeout  30;
set $wake_probe_host     "192.168.1.103";
set $wake_port           8080;
set $wake_splash         "true";

3. Save the Proxy Host. The changes take effect immediately.

Configuration Reference

Option	Nginx Variable	Default	Description
wakeonrequest.enable	-	-	Set to true to opt-in the container for management.
wakeonrequest.domain	-	-	Comma-separated domains mapped to this container (automatically falls back to root domains for subdomains like www.).
wakeonrequest.idle_timeout	$wake_idle_timeout	300	Inactivity duration in seconds before stopping the container.
wakeonrequest.start_timeout	$wake_start_timeout	30	Maximum seconds to wait for readiness probes on startup.
wakeonrequest.probe_host	$wake_probe_host	Container name	Target hostname or IP for TCP connectivity readiness check.
wakeonrequest.port	$wake_port	Exposed port	Port number for the TCP connectivity readiness check.
-	$wake_splash	"true"	Set to "false" to disable showing the waking-up splash screen (returns a 503 Retry-After response instead).
-	$wake_timer_interval	60	Background loop check frequency for idle containers.
-	$wake_poll_interval	0.5	Readiness probe retry interval during container startup.

Troubleshooting

View Engine Logs

Watch logs in real-time to debug wake-up and sleep lifecycles:

docker logs -f nginx-proxy-manager 2>&1 | grep wakeonrequest

Detailed Nginx error logs (contains OpenResty lua errors):

docker exec -it nginx-proxy-manager tail -f /data/logs/fallback_error.log

Docker Socket Permission Error

If you see permission denied warnings or docker connection failures in your logs:

sudo chmod 666 /var/run/docker.sock

Log Management

Custom logs are stored in standard locations. To prevent log exhaustion, you can manually clear them:

docker exec nginx-proxy-manager sh -c "truncate -s 0 /data/logs/fallback_error.log"

Or configure auto-rotation in your NPM compose file:

logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

Known Limitations

Mixed Splash Configuration: wakeonrequest uses a single TTL-bound shared memory key per container to track the splash screen lock. If you have multiple proxy hosts pointing to the same container where one host has the splash screen enabled and another has it disabled, a timeout on the splash-disabled host could inadvertently clear the splash screen block for the enabled host. It is recommended to keep wake_splash consistent across all proxy hosts mapping to the same container.

License

MIT License. See LICENSE for details.