# Goma Gateway – Modern, Lightweight API Gateway & Reverse Proxy # **Goma Gateway - A Lightweight API Gateway & Reverse Proxy with Declarative Config and Powerful Middleware** ## **Introduction** **Goma Gateway** is a high-performance, security-focused API Gateway built for modern developers and cloud-native environments. It combines an intuitive declarative configuration system with powerful middleware and first-class observability, helping you **route, secure, and scale traffic effortlessly**. Whether you’re managing microservices, securing public APIs, or modernizing legacy systems, Goma Gateway delivers **flexibility without unnecessary complexity**. **Architecture:** ![Goma architecture](https://raw.githubusercontent.com/jkaninda/goma-gateway/main/goma-gateway.png align="left") ## Core Capabilities ### **Routing & Traffic Management** * Declarative **YAML-based configuration** * Flexible routing for **domains, hosts, paths, WebSocket, gRPC, TCP/UDP** * Multi-domain & multi-service support in one config * Reverse proxy with backend abstraction * Traffic control: **rate limiting, load balancing, health checks** * **Canary Deployments**: Safely roll out new versions of your services with advanced canary deployment strategies: * **Weighted Backends** – Gradually shift traffic between service versions using percentage-based routing. * **Conditional Routing** – Route requests based on user groups, headers, query parameters, or cookies for targeted rollouts. ### **Security & Access Control** * Automatic HTTPS via **Let’s Encrypt** or custom TLS * **Mutual TLS (mTLS)** for client certificate authentication * Built-in authentication: **Basic Auth, JWT, OAuth, LDAP, ForwardAuth** * CORS policies, header injection, fine-grained access control * Exploit protection: **SQL injection, XSS**, and bot detection * Method restrictions and regex-based URL rewriting ### **Performance & Reliability** * **HTTP caching** (in-memory or Redis) with smart invalidation * Load balancing: round-robin, weighted, with health checks * Scalable rate limiting: local or Redis-based *(with automatic banning for repeated abuse)* ### **Operations & Monitoring** * Zero-downtime config reloads * Structured logging with configurable levels * Prometheus/Grafana metrics * Graceful error handling and backend failure interception ### **Cloud-Native Integration** * Kubernetes CRD support for native resource management * GitOps-friendly with version-controlled configs * Modular config files for organized route management * Horizontal scalability & dynamic backend updates ## **Why Choose Goma Gateway?** Goma Gateway isn’t just another reverse proxy; it’s **built for modern workflows**: * **Simple, Declarative Configuration**: Clean YAML config that’s easy to read, version-controlled, and automatable. * **First-Class Security:** TLS, authentication, exploit protection, and access control baked in. * **Live Reload & GitOps-Ready**: Perfect for CI/CD pipelines. * **Observability from Day One**: Logging and metrics built in. * **Cloud-Native**: Seamless integration with Kubernetes. **Perfect for:** Public APIs, internal microservices, legacy modernization, or any project requiring secure, scalable traffic management. ## **Quick Tutorial: Deploying Goma Gateway as a Reverse Proxy for Docker Services** ### **Prerequisites** Make sure you have: * **Docker** installed * Basic knowledge of YAML config ### **Step 1. Generate a Default Config** ```bash docker run --rm --name goma-gateway \ -v "${PWD}/config:/etc/goma/" \ jkaninda/goma-gateway config init --output /etc/goma/config.yml ``` This creates `config/config.yml` with default settings. ### **Step 2. Customize Your Configuration** Example `config.yml`: ```yaml version: 2 gateway: entryPoints: web: address: ":80" webSecure: address: ":443" routes: - path: / name: api hosts: ["api.example.com"] target: http://okapi-api:8080 middlewares: ["basic-auth", "rate-limit"] middlewares: - name: basic-auth type: basicAuth rule: users: - username: admin password: $2y$05$TIx7l8sJWvMFXw4n0GbkQuOhemPQOormacQC4W1p28TOVzJtx.XpO - name: rate-limit type: rateLimit rule: unit: minute requestsPerUnit: 60 certManager: acme: email: admin@example.com storageFile: /etc/letsencrypt/acme.json ``` ### **Step 3. Run with Docker Compose** `compose.yaml`: ```yaml services: goma-gateway: image: jkaninda/goma-gateway command: -c config.yaml restart: always ports: - "80:80" - "443:443" volumes: - ./config:/etc/goma/ - ./letsencrypt:/etc/letsencrypt okapi-api: image: jkaninda/okapi-example restart: always ``` **Your gateway is now live**, ready to route, secure, and monitor your services. ### **Step 4. Grafana Dashboard** Goma Gateway includes built-in monitoring to track the **health, performance, and behavior** of your gateway and its routes. Metrics are exposed in a **Prometheus-compatible** format, making them easy to integrate with **Prometheus** and visualize using **Grafana**. A **prebuilt Grafana dashboard** is available for quick setup and visualization. You can import it directly using: **Dashboard ID:** `23799` Enable metrics ```yaml version: 2 gateway: # Timeout settings (in seconds) timeouts: write: 30 read: 30 idle: 30 # Optional, default port 8080 entryPoints: web: address: ":80" webSecure: address: ":443" monitoring: enableMetrics: true metricsPath: /metrics extraConfig: directory: /etc/goma/extra # Directory containing extra config files watch: false # Watch for changes in extra config directory and reload after changes ``` #### Dashboard Preview ![Goma Gateway Grafana Dashboard](https://raw.githubusercontent.com/jkaninda/goma-gateway/main/docs/images/goma_gateway_observability_dashboard-23799.png align="left") ## **Links** * **GitHub**: [jkaninda/goma-gateway](https://github.com/jkaninda/goma-gateway) * **Docker Hub**: [jkaninda/goma-gateway](https://hub.docker.com/r/jkaninda/goma-gateway)