{"id":30985221,"url":"https://github.com/libops/lightsout","last_synced_at":"2025-09-12T13:07:27.666Z","repository":{"id":312596108,"uuid":"1048014047","full_name":"libops/lightsout","owner":"libops","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-31T18:19:04.000Z","size":10,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-31T20:31:08.803Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/libops.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":"2025-08-31T18:16:17.000Z","updated_at":"2025-08-31T18:18:40.000Z","dependencies_parsed_at":"2025-08-31T20:32:42.791Z","dependency_job_id":"b231bf6f-53d0-416a-8ae7-151ef415aebc","html_url":"https://github.com/libops/lightsout","commit_stats":null,"previous_names":["libops/lightsout"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/libops/lightsout","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libops%2Flightsout","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libops%2Flightsout/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libops%2Flightsout/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libops%2Flightsout/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/libops","download_url":"https://codeload.github.com/libops/lightsout/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libops%2Flightsout/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274816949,"owners_count":25355225,"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-09-12T02:00:09.324Z","response_time":60,"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-09-12T13:07:26.468Z","updated_at":"2025-09-12T13:07:27.655Z","avatar_url":"https://github.com/libops.png","language":"Go","readme":"# Lights Out\n\nA lightweight Go service that combines ping health checks with power management for GCE instances. Acts as both a health endpoint and an activity monitor that can automatically shut down instances after periods of inactivity.\n\n## Features\n\n- **HTTP Health Endpoints**: `/ping` (monitored) and `/health` (healthcheck)\n- **Activity Monitoring**: Tracks requests to `/ping` endpoint\n- **Configurable Timeouts**: Environment-controlled inactivity periods\n- **GCP Integration**: Automatic instance suspension via GCP API service\n\n## Usage\n\n### As Docker Container\n\n```bash\ndocker run -p 8808:8808 -e INACTIVITY_TIMEOUT=90 lightswitch:latest\n```\n\n### Environment Variables\n\n| Variable             | Default | Description                              |\n| -------------------- | ------- | ---------------------------------------- |\n| `PORT`               | `8808`  | HTTP server port                         |\n| `INACTIVITY_TIMEOUT` | `90`    | Seconds of inactivity before shutdown    |\n| `CHECK_INTERVAL`     | `30`    | Seconds between activity checks          |\n| `LIBOPS_PROXY_URL`   | -       | GCP proxy URL for suspension             |\n| `LIBOPS_KEEP_ONLINE` | -       | Set to \"yes\" to disable auto-shutdown    |\n| `LOG_LEVEL`          | `INFO`  | Logging level (DEBUG, INFO, WARN, ERROR) |\n\n### Endpoints\n\n- `GET /ping` - Returns \"pong\", activity is logged and monitored\n- `GET /health` - Returns \"healthy\", used for container healthchecks\n\n## Integration\n\nThis service is designed to work in tandem with [ppb (Proxy Power Button)](https://github.com/libops/ppb) to create a complete on-demand infrastructure solution:\n\n### How ppb and lightsout work together:\n\n1. **ppb (Boot)**: Acts as an ingress proxy that automatically starts GCE instances when requests arrive\n   - Receives incoming requests for dormant instances\n   - Starts the GCE instance via GCP API\n   - Proxies requests to the now-running backend\n   \n2. **lightsout (Shutdown)**: Monitors activity and automatically shuts down instances during idle periods\n   - Tracks activity via `/ping` endpoint calls\n   - Monitors for configurable inactivity timeouts\n   - Automatically suspends the GCE instance to save costs\n\n### Deployment Architecture:\n\n```\nInternet → ppb (ingress) → GCE Instance (running lightsout + your app)\n```\n\n- Deploy ppb as your public-facing service\n- Deploy lightsout alongside your application on GCE instances\n- Configure your application to periodically call `/ping` to signal activity\n- ppb handles instance startup, lightsout handles instance shutdown\n\n### Required IAM Permissions\n\nThe Google Service Account (GSA) used by this service requires the following IAM permissions:\n\n- `compute.instances.suspend` - To suspend/stop the GCE instance\n- `compute.instances.get` - To check the current status of the instance\n\nThese can be granted via the predefined `Compute Instance Admin (v1)` role, or by creating a custom role with only the specific permissions needed:\n\n```bash\n# Create custom role with minimal permissions\ngcloud iam roles create lightsout.instanceManager \\\n    --project=YOUR_PROJECT_ID \\\n    --title=\"Lightsout Instance Manager\" \\\n    --description=\"Minimal permissions for lightsout service\" \\\n    --permissions=compute.instances.suspend,compute.instances.get\n\n# Assign to service account\ngcloud projects add-iam-policy-binding YOUR_PROJECT_ID \\\n    --member=\"serviceAccount:YOUR_SERVICE_ACCOUNT@YOUR_PROJECT_ID.iam.gserviceaccount.com\" \\\n    --role=\"projects/YOUR_PROJECT_ID/roles/lightsout.instanceManager\"\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibops%2Flightsout","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flibops%2Flightsout","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibops%2Flightsout/lists"}