https://github.com/msenturk/wake-on-request
Wake-On-Request is a lightweight, high-performance container lifecycle manager for Nginx Proxy Manager.
https://github.com/msenturk/wake-on-request
docker nginx-proxy-manager on-demand openresty wake-on-demand
Last synced: about 1 month ago
JSON representation
Wake-On-Request is a lightweight, high-performance container lifecycle manager for Nginx Proxy Manager.
- Host: GitHub
- URL: https://github.com/msenturk/wake-on-request
- Owner: msenturk
- License: mit
- Created: 2026-06-14T20:37:17.000Z (about 1 month ago)
- Default Branch: master
- Last Pushed: 2026-06-15T12:10:09.000Z (about 1 month ago)
- Last Synced: 2026-06-15T12:24:04.192Z (about 1 month ago)
- Topics: docker, nginx-proxy-manager, on-demand, openresty, wake-on-demand
- Language: Shell
- Homepage:
- Size: 185 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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:
```bash
# 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:
```bash
# 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.
```bash
docker compose up -d --force-recreate
```
## 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.
```yaml
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:
```bash
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:
```nginx
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:
```bash
docker logs -f nginx-proxy-manager 2>&1 | grep wakeonrequest
```
Detailed Nginx error logs (contains OpenResty lua errors):
```bash
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:
```bash
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:
```bash
docker exec nginx-proxy-manager sh -c "truncate -s 0 /data/logs/fallback_error.log"
```
Or configure auto-rotation in your NPM compose file:
```yaml
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.