{"id":18431551,"url":"https://github.com/jkaninda/goma-gateway","last_synced_at":"2026-02-21T07:47:05.675Z","repository":{"id":260058666,"uuid":"879156725","full_name":"jkaninda/goma-gateway","owner":"jkaninda","description":"Goma Gateway – Lightweight, High-Performance API Gateway and Reverse Proxy with declarative config, robust middleware, and support for REST, GraphQL, TCP, UDP, and gRPC.","archived":false,"fork":false,"pushed_at":"2026-02-10T21:06:27.000Z","size":5521,"stargazers_count":175,"open_issues_count":0,"forks_count":17,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-02-10T21:26:48.708Z","etag":null,"topics":["api-gateway","api-management","docker","docker-proxy","go","go-proxy","golang","goma-gateway","letsencrypt","load-balancer","microservices","microservices-proxy","middleware","proxies","reverse-proxy","tcp-proxy","udp-proxy","udp-proxy-server","web-proxy"],"latest_commit_sha":null,"homepage":"https://goma.jkaninda.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jkaninda.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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},"funding":{"ko_fi":"jkaninda"}},"created_at":"2024-10-27T06:23:54.000Z","updated_at":"2026-02-10T17:58:18.000Z","dependencies_parsed_at":"2026-01-12T12:00:29.128Z","dependency_job_id":null,"html_url":"https://github.com/jkaninda/goma-gateway","commit_stats":null,"previous_names":["jkaninda/goma-gateway"],"tags_count":96,"template":false,"template_full_name":null,"purl":"pkg:github/jkaninda/goma-gateway","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkaninda%2Fgoma-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkaninda%2Fgoma-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkaninda%2Fgoma-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkaninda%2Fgoma-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jkaninda","download_url":"https://codeload.github.com/jkaninda/goma-gateway/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkaninda%2Fgoma-gateway/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29676841,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T06:23:40.028Z","status":"ssl_error","status_checked_at":"2026-02-21T06:23:39.222Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["api-gateway","api-management","docker","docker-proxy","go","go-proxy","golang","goma-gateway","letsencrypt","load-balancer","microservices","microservices-proxy","middleware","proxies","reverse-proxy","tcp-proxy","udp-proxy","udp-proxy-server","web-proxy"],"created_at":"2024-11-06T05:25:25.934Z","updated_at":"2026-02-21T07:47:05.669Z","avatar_url":"https://github.com/jkaninda.png","language":"Go","funding_links":["https://ko-fi.com/jkaninda"],"categories":["软件包","Software Packages","Go Tools"],"sub_categories":["DevOps 工具","DevOps Tools"],"readme":"# Goma Gateway — Lightweight API Gateway and Reverse Proxy with declarative config, robust middleware.\n\n```\n   ____                       \n  / ___| ___  _ __ ___   __ _ \n | |  _ / _ \\| '_ ` _ \\ / _` |\n | |_| | (_) | | | | | | (_| |\n  \\____|\\___/|_| |_| |_|\\__,_|\n  :: Goma Gateway :: - ()\n                               \n```\n---\n\n[![Tests](https://github.com/jkaninda/goma-gateway/actions/workflows/test.yml/badge.svg)](https://github.com/jkaninda/goma-gateway/actions/workflows/test.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/jkaninda/goma-gateway)](https://goreportcard.com/report/github.com/jkaninda/goma-gateway)\n[![Go](https://img.shields.io/github/go-mod/go-version/jkaninda/goma-gateway)](https://go.dev/)\n[![Go Reference](https://pkg.go.dev/badge/github.com/jkaninda/goma-gateway.svg)](https://pkg.go.dev/github.com/jkaninda/goma-gateway)\n[![GitHub Release](https://img.shields.io/github/v/release/jkaninda/goma-gateway)](https://github.com/jkaninda/goma-gateway/releases)\n![Docker Image Size (latest by date)](https://img.shields.io/docker/image-size/jkaninda/goma-gateway?style=flat-square)\n![Docker Pulls](https://img.shields.io/docker/pulls/jkaninda/goma-gateway?style=flat-square)\n\n**Goma Gateway** is a high-performance, security-focused API Gateway built for modern developers and cloud-native environments. With a powerful feature set, intuitive configuration, and first-class support for observability, Goma helps you route, secure, and scale traffic effortlessly.\n\n\n**Why \"Goma\"? 🇨🇩**\n\nThe project takes its name from Goma, a resilient city in the eastern Democratic Republic of Congo that serves as a vital crossroads connecting diverse regions. Like its namesake, Goma Gateway acts as a strategic entry point managing, securing, and directing the flow of API traffic that connects your services.\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/jkaninda/goma-gateway/main/logo.png\" width=\"150\" alt=\"Okapi logo\"\u003e\n\u003c/p\u003e\n\n\nArchitecture:\n\n\u003cimg src=\"https://raw.githubusercontent.com/jkaninda/goma-gateway/main/goma-gateway.png\" width=\"912\" alt=\"Goma architecture\"\u003e\n\n\n\n## Links\n\n- **Documentation**: [Documentation](https://jkaninda.github.io/goma-gateway)\n- **Source Code**: [Goma Gateway on GitHub](https://github.com/jkaninda/goma-gateway)\n- **Docker Image**: [jkaninda/goma-gateway](https://hub.docker.com/r/jkaninda/goma-gateway)\n- **HTTP Provider**: [Goma HTTP Provider](https://github.com/jkaninda/goma-http-provider)\n- **Docker Provider**: [Goma Docker Provider](https://github.com/jkaninda/goma-docker-provider)\n\n\n### [Documentation](https://jkaninda.github.io/goma-gateway)\n\n---\n## Features Overview\n\n**Goma Gateway** is a modern, developer-friendly API Gateway built for simplicity, security, and scale.\nMore than just a reverse proxy, it streamlines service infrastructure management with **declarative configuration** and **enterprise-grade features**.\n\n\n## Core Capabilities\n\n### **Routing \u0026 Traffic Management**\n\n* Declarative **YAML-based configuration**\n* Flexible routing for **domains, hosts, paths, WebSocket, gRPC, TCP/UDP**\n* Multi-domain \u0026 multi-service support in one config\n* Reverse proxy with backend abstraction\n* Traffic control: **rate limiting, load balancing, health checks**\n* **Canary Deployments**:\n  Safely roll out new versions of your services with advanced canary deployment strategies:\n\n  * **Weighted Backends** – Gradually shift traffic between service versions using percentage-based routing.\n  * **Conditional Routing** – Route requests based on user groups, headers, query parameters, or cookies for targeted rollouts.\n\n### **Security \u0026 Access Control**\n\nEnterprise-grade security without the enterprise complexity\n\n* Automatic HTTPS via **Let’s Encrypt** or custom TLS\n* **Mutual TLS (mTLS)** for client certificate authentication\n* Built-in authentication: **Basic Auth, JWT, OAuth, LDAP, ForwardAuth**\n* CORS policies, header injection, fine-grained access control\n* Exploit protection: **SQL injection, XSS**, and bot detection\n* Method restrictions and regex-based URL rewriting\n* **Extensible security** – Custom middleware plugins for specialized authentication and authorization logic\n\n### **Performance \u0026 Reliability**\n\n* **Intelligent caching**: HTTP caching with in-memory or Redis backend, smart cache invalidation\n* Load balancing: round-robin, weighted, with health checks\n* Scalable rate limiting: Flexible strategies to prevent abuse:\n  * Local or Redis-based for distributed systems\n  * Automatic client banning for repeated violations\n  * Customizable keys: IP address, API keys, custom headers, or session cookies\n\n### **Operations \u0026 Monitoring**\n\n* Zero-downtime config reloads\n* Structured logging with configurable levels\n* Prometheus/Grafana metrics\n* Graceful error handling and backend failure interception\n\n### **Cloud-Native Integration**\n\n* Kubernetes CRD support for native resource management\n* GitOps-friendly with version-controlled configs\n* Modular config files for organized route management\n* Horizontal scalability \u0026 dynamic backend updates\n\n---\n\n## Why Goma Gateway?\n\nMore than just a reverse proxy, Goma Gateway streamlines your services with declarative configuration and enterprise-grade features.\n\n### **1. Simple, Declarative Configuration**\n\nWrite clear YAML for routes, middleware, policies, and TLS.\nSupports single-file or multi-file setups, intuitive and maintainable.\n\n### **2. Security First**\n\n* Auto HTTPS \u0026 mTLS\n* Multiple authentication methods\n* Built-in exploit prevention\n* Fine-grained access control\n* Scalable rate limiting with abuse detection\n\n### **3. Multi-Domain \u0026 Smart Routing**\n\nHandle REST APIs, WebSocket, gRPC, intelligent host \u0026 path routing.\n\n### **4. Live Reload \u0026 GitOps Ready**\n\nApply changes instantly without restarts — perfect for CI/CD pipelines.\n\n### **5. Full Observability**\n\n* Structured logging\n* Prometheus metrics\n* Grafana dashboards\n\n### **6. Built for Speed**\n\n* Intelligent HTTP caching\n* Advanced load balancing\n* Health-aware backend routing\n\n\n**Perfect for:** Public APIs, internal microservices, legacy modernization, or any project requiring secure, scalable traffic management.\n\n\n---\n## Quickstart Guide\n\nGet started with **Goma Gateway** in just a few steps. This guide covers generating a configuration file, customizing it, validating your setup, and running the gateway with Docker.\n\n\n## Prerequisites\n\nBefore you begin, ensure you have:\n\n* **Docker** — to run the Goma Gateway container\n* **Kubernetes** *(optional)* — if you plan to deploy on Kubernetes\n\n\n## Installation Steps\n\n### 1. Generate a Default Configuration\n\nRun the following command to create a default configuration file (`config.yml`):\n\n```bash\ndocker run --rm --name goma-gateway \\\n  -v \"${PWD}/config:/etc/goma/\" \\\n  jkaninda/goma-gateway config init --output /etc/goma/config.yml\n```\n\nThis will generate the configuration under `./config/config.yml`.\n\n\n### 2. Customize the Configuration\n\nEdit `./config/config.yml` to define your **routes**, **middlewares**, **backends**, and other settings.\n\n\n### 3. Validate Your Configuration\n\nCheck the configuration for errors before starting the server:\n\n```bash\ndocker run --rm --name goma-gateway \\\n  -v \"${PWD}/config:/etc/goma/\" \\\n  jkaninda/goma-gateway config check --config /etc/goma/config.yml\n```\n\nFix any reported issues before proceeding.\n\n\n### 4. Start the Gateway\n\nLaunch the server with your configuration and Let's Encrypt volumes:\n\n```bash\ndocker run --rm --name goma-gateway \\\n  -v \"${PWD}/config:/etc/goma/\" \\\n  -v \"${PWD}/letsencrypt:/etc/letsencrypt\" \\\n  -p 8080:8080 \\\n  -p 8443:8443 \\\n  jkaninda/goma-gateway --config /etc/goma/config.yml\n```\n\nBy default, Goma Gateway listens on:\n\n* **8080** → HTTP (`web` entry point)\n* **8443** → HTTPS (`webSecure` entry point)\n\n\n### 5. (Optional) Use Standard Ports 80 \u0026 443\n\nTo run on standard HTTP/HTTPS ports, update your config file:\n\n```yaml\nversion: 2\ngateway:\n  entryPoints:\n    web:\n      address: \":80\"\n    webSecure:\n      address: \":443\"\n```\n\nStart the container with:\n\n```bash\ndocker run --rm --name goma-gateway \\\n  -v \"${PWD}/config:/etc/goma/\" \\\n  -v \"${PWD}/letsencrypt:/etc/letsencrypt\" \\\n  -p 80:80 \\\n  -p 443:443 \\\n  jkaninda/goma-gateway --config /etc/goma/config.yml\n```\n\n\n### 6. Health Checks\n\nGoma Gateway exposes the following endpoints:\n\n* Gateway health:\n\n  * `/readyz`\n  * `/healthz`\n* Routes health:\n\n  * `/healthz/routes`\n\n\n### 7. Deploy with Docker Compose\n\nA simple `docker-compose` setup:\n\n**`config.yaml`**\n\n```yaml\nversion: 2\ngateway:\n  entryPoints:\n    web:\n      address: \":80\"\n    webSecure:\n      address: \":443\"\n  log:\n    level: info\n  routes:\n    - name: api-example\n      path: /\n      target: http://api-example:8080\n      middlewares: [\"rate-limit\",\"basic-auth\"]\n    - name: host-example\n      path: /api\n      rewrite: /\n      hosts:\n        - api.example.com\n      backends:\n        - endpoint: https://api-1.example.com\n          weight: 20\n        - endpoint: https://api-2.example.com\n          weight: 80\n      healthCheck:\n        path: /\n        interval: 30s\n        timeout: 10s\nmiddlewares:\n  - name: rate-limit\n    type: rateLimit\n    rule:\n      unit: minute\n      requestsPerUnit: 20\n      banAfter: 5\n      banDuration: 5m\n  - name: basic-auth\n    type: basicAuth\n    paths: [\"/admin\",\"/docs\",\"/openapi\"]\n    rule:\n      realm: Restricted\n      forwardUsername: true\n      users:\n        - username: admin\n          password: $2y$05$TIx7l8sJWvMFXw4n0GbkQuOhemPQOormacQC4W1p28TOVzJtx.XpO # bcrypt hash for 'admin'\n        - username: user\n          password: password\ncertManager:\n  acme:\n    ## Uncomment email to enable Let's Encrypt\n    # email: admin@example.com # Email for ACME registration\n    storageFile: /etc/letsencrypt/acme.json\n```\n\n**`compose.yaml`**\n\n```yaml\nservices:\n  goma-gateway:\n    image: jkaninda/goma-gateway\n    command: -c /etc/goma/config.yaml\n    ports:\n      - \"80:80\"\n      - \"443:443\"\n    volumes:\n      - ./config:/etc/goma/\n      - ./letsencrypt:/etc/letsencrypt\n\n  api-example:\n    image: jkaninda/okapi-example\n```\n\nVisit http://localhost/docs to see the documentation\n\n---\n\n### 8. Docker / Swarm Provider (External)\n\nGoma Gateway does not include a built-in Docker provider to remain lightweight and modular.\nIf you deploy services using **Docker Compose** or **Docker Swarm**, the **Goma Docker Provider** automatically generates gateway configuration from container labels.\n\nThis approach will feel familiar if you’ve used **Traefik**: routing rules, services, and middleware are declared directly on containers.\n\nA simple `docker-compose` setup:\n\n```yaml\nservices:\n  goma-gateway:\n    image: jkaninda/goma-gateway:latest\n    ports:\n      - \"80:80\"\n      - \"443:443\"\n    volumes:\n      - ./:/etc/goma\n      - providers:/etc/goma/providers\n    environment:\n      -  GOMA_LOG_LEVEL=info\n      -  GOMA_EXTRA_CONFIG_DIR=/etc/goma/providers\n      -  GOMA_EXTRA_CONFIG_WATCH=true\n      -  GOMA_ENTRYPOINT_WEB_ADDRESS=:80\n      -  GOMA_ENTRYPOINT_WEB_SECURE_ADDRESS=:443\n    networks:\n      - goma-net\n\n  goma-provider:\n    image: jkaninda/goma-docker-provider\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock:ro # Required\n      - providers:/etc/goma/providers\n    environment:\n      - GOMA_OUTPUT_DIR=/etc/goma/providers # Optional, default /etc/goma/providers\n      - GOMA_ENABLE_SWARM=false # Enable Swarm mode, default false\n    networks:\n      - goma-net\n  # Web Service - Minimal Configuration\n  web-service:\n    image: jkaninda/okapi-example\n    labels:\n      - \"goma.enable=true\" # Required to expose the service\n      - \"goma.port=8080\"\n      - \"goma.hosts=example.com, www.example.com\" # Optional\n    networks:\n      - goma-net\nvolumes:\n  providers: {}\nnetworks:\n  goma-net:\n    driver: bridge\n```\n\n👉 See:\n[Goma Docker Provider](https://github.com/jkaninda/goma-docker-provider)\n\n---\n### 9. Kubernetes deployment\n\n#### Basic Deployment\n\n```shell\nkubectl apply -f https://raw.githubusercontent.com/jkaninda/goma-gateway/main/examples/k8s-basic-deployment.yaml\n```\n\n\n### 10. HTTP API Provider (External)\n\nThe **Goma HTTP Provider** exposes a REST API for managing routes, middleware, and gateway configuration dynamically.\n\nIt’s ideal for:\n\n* Control planes\n* Automation workflows\n* Internal platform tools\n\n👉 See:\n[Goma HTTP Provider](https://github.com/jkaninda/goma-http-provider)\n\n### 11. Grafana Dashboard\n\nGoma Gateway offers built-in monitoring capabilities to help you track the **health**, **performance**, and **behavior** of your gateway and its routes. Metrics are exposed in a **Prometheus-compatible** format and can be visualized using tools like **Prometheus** and **Grafana**.\n\nA prebuilt **Grafana dashboard** is available to visualize metrics from Goma Gateway.\n\nYou can import it using dashboard ID: [23799](https://grafana.com/grafana/dashboards/23799)\n\n\n#### Dashboard Preview\n\n![Goma Gateway Grafana Dashboard](https://raw.githubusercontent.com/jkaninda/goma-gateway/main/docs/images/goma_gateway_observability_dashboard-23799.png)\n\n\n### 12. Production Deployment Guide\n\nFor production deployments, use the example from the link below:\n\n[production-deployment](https://github.com/jkaninda/goma-gateway-production-deployment).\n\n\n---\n## Supported Systems\n\n- [x] Linux\n- [x] MacOS\n- [x] Windows\n\nPlease download the binary from the [release page](https://github.com/jkaninda/goma-gateway/releases).\n\nInit configs:\n\n```shell\n./goma config init --output config.yml\n```\n\nTo run\n```shell\n./goma server --config config.yml\n```\n---\n## Deployment\n\n- Docker\n- Kubernetes\n\n## Contributing\n\nThe Goma Gateway project welcomes all contributors. We appreciate your help!\n\n## 🌟 Star History\n\n⭐ If you find Goma Gateway useful, please consider giving it a star on [GitHub](https://github.com/jkaninda/goma-gateway)!\n\n[![Star History Chart](https://api.star-history.com/svg?repos=jkaninda/goma-gateway\u0026type=Date)](https://star-history.com/#jkaninda/goma-gateway\u0026Date)\n\n\n## Give a Star! ⭐\n\nIf this project helped you, do not skip on giving it a star. Thanks!\n\n---\n\n## License\n\nThis project is licensed under the Apache 2.0 License. See the LICENSE file for details.\n\n\n## Copyright\n\nCopyright (c) 2024–2025 Jonas Kaninda and contributors\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eBuilt with ❤️ for the developer community\u003c/strong\u003e\n\u003c/p\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjkaninda%2Fgoma-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjkaninda%2Fgoma-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjkaninda%2Fgoma-gateway/lists"}