{"id":29482609,"url":"https://github.com/darksworm/go-wol-proxy","last_synced_at":"2025-10-08T08:58:59.826Z","repository":{"id":297621899,"uuid":"997379021","full_name":"darksworm/go-wol-proxy","owner":"darksworm","description":"A Wake-on-LAN reverse-proxy service that automatically wakes up servers when requests are made to them.","archived":false,"fork":false,"pushed_at":"2025-09-07T13:32:27.000Z","size":74,"stargazers_count":117,"open_issues_count":2,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-21T06:46:49.570Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/darksworm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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":"2025-06-06T12:31:47.000Z","updated_at":"2025-09-11T19:46:38.000Z","dependencies_parsed_at":"2025-06-06T13:32:39.196Z","dependency_job_id":"630eed46-b775-4987-a3f7-26e5e655cae1","html_url":"https://github.com/darksworm/go-wol-proxy","commit_stats":null,"previous_names":["darksworm/go-wol-proxy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/darksworm/go-wol-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darksworm%2Fgo-wol-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darksworm%2Fgo-wol-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darksworm%2Fgo-wol-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darksworm%2Fgo-wol-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/darksworm","download_url":"https://codeload.github.com/darksworm/go-wol-proxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darksworm%2Fgo-wol-proxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278916428,"owners_count":26068091,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"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":[],"created_at":"2025-07-15T02:01:17.055Z","updated_at":"2025-10-08T08:58:59.818Z","avatar_url":"https://github.com/darksworm.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Go WOL Proxy\n\nA Wake-on-LAN proxy service written in Go that automatically wakes up servers when requests are made to them.\n\n## Features\n\n- Proxies HTTP requests to configured target servers\n- Automatically sends Wake-on-LAN packets to wake up offline servers\n- Monitors server health with configurable intervals\n- Caches health status to minimize latency for frequent requests\n- Packaged as a Docker container for easy deployment\n- :star: new :star: Supports graceful shutdown of servers after a period of inactivity\n\n## Configuration\n\nThe service is configured using a TOML file. Here's an example configuration:\n\n```toml\nport = \":8080\"                 # Port to listen on\ntimeout = \"1m\"                 # How long to wait for server to wake up\npoll_interval = \"5s\"           # How often to check health during wake-up\nhealth_check_interval = \"30s\"  # Background health check frequency\nhealth_cache_duration = \"10s\"  # How long to trust cached health status\n\n# Optional SSL configuration Do not add these values unless you plan to use TLS/HTTPS\nssl_certificate = \"/path/to/cert.pem\"   # Path to your SSL certificate\nssl_certificate_key = \"/path/to/key.pem\" # Path to your SSL private key\n\n\n[[targets]]\nname = \"service\"\nhostname = \"service.host.com\"                 # The \"external\" hostname - what this server receives as a Host header\ndestination = \"http://service.local\"          # The actual url to the server\nhealth_endpoint = \"http://service.local/ping\" # url to check health\nmac_address = \"7c:8b:ad:da:be:51\"             # MAC address for WOL\nbroadcast_ip = \"10.0.0.255\"                   # Broadcast IP for WOL\nwol_port = 9                                  # Port for WOL packets\n# Optional: Graceful shutdown configuration (SSH or HTTP)\ninactivity_threshold = \"1h\"                   # Shut down after 1 hour of inactivity\n\n# Option A: SSH-based shutdown (use either Option A or Option B, not both)\nssh_host = \"service.local:22\"                 # SSH host:port for shutdown\nssh_user = \"wol-proxy\"                        # SSH username for shutdown\nssh_key_path = \"/app/private_key\"             # Path to SSH private key\nshutdown_command = \"sudo systemctl suspend\"   # Command to execute for shutdown\n# ^ take care - wake from suspend / shutdown can be flaky on some systems.\n# if your machine doesnt wake from your chosen \"sleep\" mode, try another.\n\n# Option B: HTTP-based shutdown (use either Option A or Option B, not both)\n#shutdown_http_url = \"http://service.local/api/shutdown\" # URL to trigger shutdown (final response validated)\n#shutdown_http_method = \"POST\"                              # Optional; defaults to POST\n#shutdown_http_ok_status = 0                                 # Optional; 0=accept any 2xx (default). Set e.g. 202 to require specific code\n\n[[targets]]\nname = \"service2\"\nhostname = \"service2.host.com\"\ndestination = \"http://service2.local\"\nhealth_endpoint = \"http://service2.local/ping\"\nmac_address = \"c9:69:45:d2:1e:12\"\nbroadcast_ip = \"10.0.0.255\"\nwol_port = 9\n```\n\n## Docker Usage\n\n### Pull the Docker Image\n\n```bash\ndocker pull ghcr.io/darksworm/go-wol-proxy:latest\n```\n\n### Run the Docker Container\n\n```bash\n# Note: network mode \"host\" is required for Wake-on-LAN packets to be sent correctly\ndocker run --network host -v /path/to/config.toml:/app/config.toml ghcr.io/darksworm/go-wol-proxy:latest\n```\n\n### Build the Docker Image Locally\n\n```bash\ndocker build -t go-wol-proxy .\n```\n\n### Run the Locally Built Image\n\n```bash\n# Note: network mode \"host\" is required for Wake-on-LAN packets to be sent correctly\ndocker run --network host -v /path/to/config.toml:/app/config.toml go-wol-proxy\n```\n\n### Docker Compose Usage\n\nCreate a `docker-compose.yml` file with the following content:\n\n```yaml\nversion: '3'\n\nservices:\n  go-wol-proxy:\n    image: ghcr.io/darksworm/go-wol-proxy:latest\n    # Note: network mode \"host\" is required for Wake-on-LAN packets to be sent correctly\n    network_mode: host\n    restart: unless-stopped\n    volumes:\n      - ./config.toml:/app/config.toml\n      # Optional: SSH private key for graceful shutdown\n      - ./private_key:/app/private_key\n```\n\nRun the container with Docker Compose:\n\n```bash\ndocker-compose up -d\n```\n\n## Graceful Shutdown Options\n\n- Trigger a shutdown after a period of inactivity using SSH or HTTP.\n- Exactly one mechanism must be configured per target: SSH or HTTP, not both.\n\n### SSH-based Shutdown\n- Use `ssh_host`, `ssh_user`, `ssh_key_path`, and `shutdown_command`.\n- The proxy executes the command over SSH when the target is inactive.\n\n### HTTP-based Shutdown\n- Use `shutdown_http_url` to enable HTTP shutdown.\n- `shutdown_http_method` defaults to `POST` if not specified.\n- By default, any 2xx status code counts as success; set `shutdown_http_ok_status` to require a specific code.\n- The HTTP client follows redirects and validates the final response code.\n- The shutdown HTTP request uses a 10s timeout.\n\n### Validation Rules\n- You cannot set both `shutdown_http_url` and `shutdown_command` for the same target.\n- If `shutdown_http_method` and/or `shutdown_http_ok_status` are set, `shutdown_http_url` must also be set.\n\n### Similar projects:\n1. traefik-wol: [traefiklabs](https://plugins.traefik.io/plugins/642498d26d4f66a5a8a59d25/wake-on-lan), [github](https://github.com/MarkusJx/traefik-wol)\n2. caddy-wol: [github](https://github.com/dulli/caddy-wol)\n\n## Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and commit conventions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarksworm%2Fgo-wol-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdarksworm%2Fgo-wol-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarksworm%2Fgo-wol-proxy/lists"}