{"id":51080633,"url":"https://github.com/msenturk/wake-on-request","last_synced_at":"2026-06-23T17:32:47.761Z","repository":{"id":364869344,"uuid":"1269532014","full_name":"msenturk/wake-on-request","owner":"msenturk","description":"Wake-On-Request is a lightweight, high-performance container lifecycle manager for Nginx Proxy Manager.","archived":false,"fork":false,"pushed_at":"2026-06-15T12:10:09.000Z","size":189,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-15T12:24:04.192Z","etag":null,"topics":["docker","nginx-proxy-manager","on-demand","openresty","wake-on-demand"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/msenturk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-14T20:37:17.000Z","updated_at":"2026-06-15T12:10:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/msenturk/wake-on-request","commit_stats":null,"previous_names":["msenturk/wakeonnpm","msenturk/wake-on-request"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/msenturk/wake-on-request","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msenturk%2Fwake-on-request","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msenturk%2Fwake-on-request/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msenturk%2Fwake-on-request/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msenturk%2Fwake-on-request/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/msenturk","download_url":"https://codeload.github.com/msenturk/wake-on-request/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msenturk%2Fwake-on-request/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34700907,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","nginx-proxy-manager","on-demand","openresty","wake-on-demand"],"created_at":"2026-06-23T17:32:46.954Z","updated_at":"2026-06-23T17:32:47.756Z","avatar_url":"https://github.com/msenturk.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Wake-On-Request\n\nWake-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.\n\n## Features\n\n* Zero-UI Configuration: Configure containers entirely via Docker labels. The installer will patch your compose files automatically.\n* NPM Advanced Tab Configuration: Configure containers in the NPM Web UI using simple Nginx variables.\n* Global Interception: Incoming requests are intercepted globally via a single injection block. No individual proxy host needs custom Lua access blocks.\n* 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.\n* Automated Cleanup: The installer automatically scans NPM's database to detect and clean up old, deprecated inline Lua access blocks.\n* 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.\n* 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.\n\n## Phase 1: Installation and Setup\n\nRun these steps in the directory where your Nginx Proxy Manager compose file is located.\n\n### 1. Run the Installer\n\nRun the script to download the engine files, scan your containers, and inject the global volume mounts into your NPM service definition:\n\n```bash\n# Download the installer\ncurl -O https://raw.githubusercontent.com/msenturk/wake-on-request/master/install.py\n\n# Run interactively (will prompt to configure discovered containers)\nsudo python3 install.py\n```\n\nAdvanced CLI Options:\n\n```bash\n# Target a specific NPM directory (positional or via --path)\nsudo python3 install.py /path/to/nginx-proxy-manager\n# or\nsudo python3 install.py --path /path/to/nginx-proxy-manager\n\n# Only configure a specific container (skips prompts for others)\nsudo python3 install.py --container my-app\n\n# Manually specify the NPM container name or ID\nsudo python3 install.py --npm my-custom-npm-container\n\n# Preview proposed changes without modifying anything\nsudo python3 install.py --dry-run\n```\n\n### 2. Apply NPM Changes\n\nRestart your NPM stack to load the Wake-On-Request OpenResty plugin. This is only required once during the initial installation.\n\n```bash\ndocker compose up -d --force-recreate \u003cnpm-service-name\u003e\n```\n\n## Phase 2: Container Configuration\n\nTo 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.\n\n### Method A: Docker Labels (Recommended)\n\nAdd configuration parameters directly to your application's compose file. No changes are needed in Nginx Proxy Manager.\n\n```yaml\nservices:\n  my-app:\n    image: my-app:latest\n    container_name: my-app\n    restart: \"no\"\n    expose:\n      - \"8080\"\n    labels:\n      - \"wakeonrequest.enable=true\"\n      - \"wakeonrequest.domain=app.example.com\"\n      - \"wakeonrequest.idle_timeout=300\"\n      - \"wakeonrequest.start_timeout=30\"\n      - \"wakeonrequest.probe_host=192.168.1.103\"\n      - \"wakeonrequest.port=8080\"\n    networks:\n      - npm_proxy\n```\n\nApply the changes by recreating the container:\n```bash\ndocker compose up -d --force-recreate my-app\n```\n\n### Method B: NPM Advanced Tab\n\nIf you prefer not to add labels to your container, you can configure it entirely inside Nginx Proxy Manager's Web UI.\n\n1. Edit your Proxy Host in the NPM Admin dashboard.\n2. Go to the Advanced Tab and paste the Nginx variable definitions:\n\n```nginx\nset $wake_container      \"my-container-name\";\nset $wake_idle_timeout   300;\nset $wake_start_timeout  30;\nset $wake_probe_host     \"192.168.1.103\";\nset $wake_port           8080;\nset $wake_splash         \"true\";\n```\n\n3. Save the Proxy Host. The changes take effect immediately.\n\n## Configuration Reference\n\n| Option | Nginx Variable | Default | Description |\n| :--- | :--- | :--- | :--- |\n| `wakeonrequest.enable` | - | - | Set to `true` to opt-in the container for management. |\n| `wakeonrequest.domain` | - | - | Comma-separated domains mapped to this container (automatically falls back to root domains for subdomains like `www.`). |\n| `wakeonrequest.idle_timeout` | `$wake_idle_timeout` | `300` | Inactivity duration in seconds before stopping the container. |\n| `wakeonrequest.start_timeout` | `$wake_start_timeout` | `30` | Maximum seconds to wait for readiness probes on startup. |\n| `wakeonrequest.probe_host` | `$wake_probe_host` | Container name | Target hostname or IP for TCP connectivity readiness check. |\n| `wakeonrequest.port` | `$wake_port` | Exposed port | Port number for the TCP connectivity readiness check. |\n| - | `$wake_splash` | `\"true\"` | Set to `\"false\"` to disable showing the waking-up splash screen (returns a 503 Retry-After response instead). |\n| - | `$wake_timer_interval` | `60` | Background loop check frequency for idle containers. |\n| - | `$wake_poll_interval` | `0.5` | Readiness probe retry interval during container startup. |\n\n## Troubleshooting\n\n### View Engine Logs\n\nWatch logs in real-time to debug wake-up and sleep lifecycles:\n\n```bash\ndocker logs -f nginx-proxy-manager 2\u003e\u00261 | grep wakeonrequest\n```\n\nDetailed Nginx error logs (contains OpenResty lua errors):\n```bash\ndocker exec -it nginx-proxy-manager tail -f /data/logs/fallback_error.log\n```\n\n### Docker Socket Permission Error\n\nIf you see permission denied warnings or docker connection failures in your logs:\n```bash\nsudo chmod 666 /var/run/docker.sock\n```\n\n### Log Management\n\nCustom logs are stored in standard locations. To prevent log exhaustion, you can manually clear them:\n\n```bash\ndocker exec nginx-proxy-manager sh -c \"truncate -s 0 /data/logs/fallback_error.log\"\n```\n\nOr configure auto-rotation in your NPM compose file:\n\n```yaml\nlogging:\n  driver: \"json-file\"\n  options:\n    max-size: \"10m\"\n    max-file: \"3\"\n```\n\n## Known Limitations\n\nMixed 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.\n\n## License\n\nMIT License. See LICENSE for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsenturk%2Fwake-on-request","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmsenturk%2Fwake-on-request","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsenturk%2Fwake-on-request/lists"}