{"id":30856838,"url":"https://github.com/cyrof/gophergate","last_synced_at":"2026-05-07T05:37:27.985Z","repository":{"id":313306279,"uuid":"1049060655","full_name":"Cyrof/GopherGate","owner":"Cyrof","description":"A WireGuard VPN manager for my Raspberry Pi k3s cluster, featuring a Go-based gRPC agent and a lighweight web UI.","archived":false,"fork":false,"pushed_at":"2025-09-05T05:57:00.000Z","size":7,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"dev","last_synced_at":"2025-09-05T07:29:23.539Z","etag":null,"topics":["docker-compose","golang","grpc-go","kubernetes","vpn","wireguard"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cyrof.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-09-02T12:35:21.000Z","updated_at":"2025-09-05T05:56:59.000Z","dependencies_parsed_at":"2025-09-05T07:29:28.158Z","dependency_job_id":"bfc0bd20-559c-4253-9409-cc762531b0bc","html_url":"https://github.com/Cyrof/GopherGate","commit_stats":null,"previous_names":["cyrof/gophergate"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Cyrof/GopherGate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cyrof%2FGopherGate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cyrof%2FGopherGate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cyrof%2FGopherGate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cyrof%2FGopherGate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cyrof","download_url":"https://codeload.github.com/Cyrof/GopherGate/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cyrof%2FGopherGate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274034027,"owners_count":25210982,"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-07T02:00:09.463Z","response_time":67,"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-compose","golang","grpc-go","kubernetes","vpn","wireguard"],"created_at":"2025-09-07T12:14:14.873Z","updated_at":"2026-05-07T05:37:27.979Z","avatar_url":"https://github.com/Cyrof.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# GopherGate\r\n\r\nGopherGate is a WireGuard management control plane built in Go.\r\n\r\nIt provides structured, automated peer lifecycle management through a clean separation between:\r\n\r\n- UI (Control Interface)\r\n- Agent (WireGuard Controller)\r\n- PostgreSQL (Persistence Layer)\r\n- WireGuard (Network Layer)\r\n\r\nInstead of editing WireGuard configs manually, GopherGate introduces a backend service layer with persistence and API access.\r\n\r\n## Architecture Overview\r\n\r\nGopherGate follows a gRPC-based control architecture.\r\n![gophergate architecture](./assets/GopherGate-Architecture.drawio.png)\r\n\r\n## Component Responsibilities\r\n\r\n### gophergate-wg-agent\r\n\r\n- Manages WireGuard peers\r\n- Hosts the gRPC server\r\n- Persists peer metadata to PostgreSQL\r\n- Talks to kernel using `wgctrl-go`\r\n- Only component allowed to modify WireGuard state\r\n\r\nModes:\r\n\r\n- CLI mode\r\n- gRPC server mode (`serve`)\r\n\r\n### gophergate-ui\r\n\r\n- Connects to agent via gRPC\r\n- Provides management interface\r\n- Displays peer status\r\n- Does not modify WireGuard directly\r\n\r\n### PostgreSQL\r\n\r\nStores:\r\n\r\n- Peer metadata\r\n- Key references\r\n- Future audit logs\r\n\r\n## Development Environment\r\n\r\nLocated under:\r\n\r\n```code\r\n/dev-sim\r\n```\r\n\r\nThis provides:\r\n\r\n- WireGuard (host network mode)\r\n- PostgreSQL\r\n- Local simulation stack\r\n\r\n### Start\r\n\r\n```bash\r\ncd dev-sim\r\ndocker-compose -f dev-sim.yaml up -d\r\n```\r\n\r\n### Run agent\r\n\r\n```bash\r\nsudo go run ./cmd/gophergate-wg-agent serve\r\n```\r\n\r\n### Run UI\r\n\r\n```bash\r\nsudo go run ./cmd/gophergate-ui\r\n```\r\n\r\n## Production Deployment\r\n\r\nProduction deployments should use the official Helm chart repository.\r\n\r\n### Helm Chart (Official Deployment Method)\r\n\r\nThe production deployment for GopherGate is maintained in a separate repository:\r\n\r\n**Helm Chart Repository:** [gophergate](https://github.com/Cyrof/CyroStack/tree/main/gophergate-deploy/gophergate)\r\n\r\nThe Helm chart deploys:\r\n\r\n- gophergate-wg-agent\r\n- gophergate-ui\r\n- PostgreSQL\r\n- Required services\r\n- Proper host networking / security context\r\n\r\nThe Helm chart is the recommended and supported way to deploy GopherGate in:\r\n\r\n- Kubernetes\r\n- k3s\r\n- On-prem clusters\r\n\r\n## Docker Image\r\n\r\nBoth the Agent and UI images are published under a single Docker repository [cyrof/gophergate](https://hub.docker.com/repository/docker/cyrof/gophergate/general). They are differentiated by tags.\r\n\r\n### Agent Image\r\n\r\n```code\r\ncyrof/gophergate:gophergate-wg-agent-latest\r\ncyrof/gophergate:gophergate-wg-agent-\u003cversion\u003e\r\n```\r\n\r\n#### Behavior\r\n\r\n- Automatically runs in `serve` mode\r\n- Hosts the gRPC server\r\n- Manages WireGuard peers\r\n- Persists to PostgreSQL\r\n\r\n#### Requirements\r\n\r\n- `CAP_NET_ADMIN`\r\n- WireGuard kernel module available on host\r\n- Host networking recommended\r\n- PostgreSQL accessible\r\n\r\nExample run (standalone test only):\r\n\r\n```bash\r\ndocker run -d \\\r\n    --name gophergate-agent \\\r\n    --network host \\\r\n    --cap-add NET_ADMIN \\\r\n    -e DATABASE_URL=postgres://... \\\r\n    cyrof/gophergate:gophergate-wg-agent-latest\r\n```\r\n\r\n### UI Image\r\n\r\n```code\r\ncyrof/gophergate:gophergate-ui-latest\r\ncyrof/gophergate:gophergate-ui-\u003cversion\u003e\r\n```\r\n\r\n#### Behavior\r\n\r\n- Connects to the Agent via gRPC\r\n- Provides management interface\r\n- Does not directly access WireGuard\r\n\r\nExample run:\r\n\r\n```bash\r\ndocker run -d \\\r\n    --name gophergate-ui \\\r\n    -p 3000:3000 \\\r\n    -e AGENT_GRPC_ADDR=\u003cagent-host\u003e:\u003cport\u003e \\\r\n    cyrof/gophergate:gophergate-ui-latest\r\n```\r\n\r\n## Repository Structure\r\n\r\n```code\r\nGopherGate/\r\n├── assets\r\n├── dev-sim\r\n├── docs\r\n├── gophergate-core\r\n├── gophergate-ui\r\n├── gophergate-wg-agent\r\n├── LICENSE\r\n└── README.md\r\n```\r\n\r\n## Phase Status\r\n\r\n### Phase 1 \u0026mdash; Core Control Plane (Completed)\r\n\r\n- Peer CRUD\r\n- PostgreSQL persistence\r\n- gRPC server\r\n- CLI interface\r\n- Development simulation environment\r\n\r\n### Phase 2 \u0026mdash; QoL + UI Improvements (In Progress)\r\n\r\n- Auto key generation\r\n- Config export\r\n- QR code generation\r\n- UI polish\r\n- Bug fixes\r\n\r\n## Design Principles\r\n\r\n- Clear separation of control and execution\r\n- Agent is sole authority over through gRPC\r\n- UI communicates only through gRPC\r\n- Database-backed persistence\r\n- Kubernetes-ready deployment model\r\n\r\n## Security (Current)\r\n\r\n- Agent requires root or `CAP_NET_ADMIN`\r\n- gRPC currently assumes trusted network\r\n- Authentication \u0026 RBAC planned\r\n- TLS support planned for gRPC\r\n\r\n## Roadmap\r\n\r\n- RBAC\r\n- TLS-secured gRPC\r\n- Observability (Prometheus)\r\n- Audit logging\r\n- HA agent model\r\n- Multi-node support\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyrof%2Fgophergate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyrof%2Fgophergate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyrof%2Fgophergate/lists"}