Goma Gateway — Lightweight API Gateway and Reverse Proxy with declarative config, robust middleware.

   ____                       
  / ___| ___  _ __ ___   __ _ 
 | |  _ / _ \| '_ ` _ \ / _` |
 | |_| | (_) | | | | | | (_| |
  \____|\___/|_| |_| |_|\__,_|
  :: Goma Gateway :: - ()
                               

---

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.

Why "Goma"? 🇨🇩

The 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.

Architecture:

Links

• Documentation: Documentation
• Source Code: Goma Gateway on GitHub
• Docker Image: jkaninda/goma-gateway
• Goma Admin(Control Plane): Goma Admin
• HTTP Provider: Goma HTTP Provider
• Docker Provider: Goma Docker Provider

Documentation

---

Features Overview

Goma Gateway is a modern, developer-friendly API Gateway built for simplicity, security, and scale. More than just a reverse proxy, it streamlines service infrastructure management with declarative configuration and enterprise-grade features.

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

Enterprise-grade security without the enterprise complexity

• 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
• Extensible security – Custom middleware plugins for specialized authentication and authorization logic

Performance & Reliability

• Intelligent caching: HTTP caching with in-memory or Redis backend, smart cache invalidation
• Load balancing: round-robin, weighted, with health checks
• Scalable rate limiting: Flexible strategies to prevent abuse:
  • Local or Redis-based for distributed systems
  • Automatic client banning for repeated violations
  • Customizable keys: IP address, API keys, custom headers, or session cookies

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 Goma Gateway?

More than just a reverse proxy, Goma Gateway streamlines your services with declarative configuration and enterprise-grade features.

1. Simple, Declarative Configuration

Write clear YAML for routes, middleware, policies, and TLS. Supports single-file or multi-file setups, intuitive and maintainable.

2. Security First

• Auto HTTPS & mTLS
• Multiple authentication methods
• Built-in exploit prevention
• Fine-grained access control
• Scalable rate limiting with abuse detection

3. Multi-Domain & Smart Routing

Handle REST APIs, WebSocket, gRPC, intelligent host & path routing.

4. Live Reload & GitOps Ready

Apply changes instantly without restarts — perfect for CI/CD pipelines.

5. Full Observability

• Structured logging
• Prometheus metrics
• Grafana dashboards

6. Built for Speed

• Intelligent HTTP caching
• Advanced load balancing
• Health-aware backend routing

Perfect for: Public APIs, internal microservices, legacy modernization, or any project requiring secure, scalable traffic management.

---

Quickstart Guide

Get 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.

Prerequisites

Before you begin, ensure you have:

• Docker — to run the Goma Gateway container
• Kubernetes (optional) — if you plan to deploy on Kubernetes

Installation Steps

1. Generate a Default Configuration

Run the following command to create a default configuration file (config.yml):

docker run --rm --name goma-gateway \
  -v "${PWD}/config:/etc/goma/" \
  jkaninda/goma-gateway config init --output /etc/goma/config.yml

This will generate the configuration under ./config/config.yml.

2. Customize the Configuration

Edit ./config/config.yml to define your routes, middlewares, backends, and other settings.

3. Validate Your Configuration

Check the configuration for errors before starting the server:

docker run --rm --name goma-gateway \
  -v "${PWD}/config:/etc/goma/" \
  jkaninda/goma-gateway config check --config /etc/goma/config.yml

Fix any reported issues before proceeding.

4. Start the Gateway

Launch the server with your configuration and Let's Encrypt volumes:

docker run --rm --name goma-gateway \
  -v "${PWD}/config:/etc/goma/" \
  -v "${PWD}/letsencrypt:/etc/letsencrypt" \
  -p 8080:8080 \
  -p 8443:8443 \
  jkaninda/goma-gateway --config /etc/goma/config.yml

By default, Goma Gateway listens on:

• 8080 → HTTP (web entry point)
• 8443 → HTTPS (webSecure entry point)

5. (Optional) Use Standard Ports 80 & 443

To run on standard HTTP/HTTPS ports, update your config file:

version: 2
gateway:
  entryPoints:
    web:
      address: ":80"
    webSecure:
      address: ":443"

Start the container with:

docker run --rm --name goma-gateway \
  -v "${PWD}/config:/etc/goma/" \
  -v "${PWD}/letsencrypt:/etc/letsencrypt" \
  -p 80:80 \
  -p 443:443 \
  jkaninda/goma-gateway --config /etc/goma/config.yml

6. Health Checks

Goma Gateway exposes the following endpoints:

• Gateway health:

  • /readyz
  • /healthz

• Routes health:

  • /healthz/routes

7. Deploy with Docker Compose

A simple docker-compose setup:

config.yaml

version: 2
gateway:
  entryPoints:
    web:
      address: ":80"
    webSecure:
      address: ":443"
  log:
    level: info
  routes:
    - name: api-example
      path: /
      target: http://api-example:8080
      middlewares: ["rate-limit","basic-auth"]
    - name: host-example
      path: /api
      rewrite: /
      hosts:
        - api.example.com
      backends:
        - endpoint: https://api-1.example.com
          weight: 20
        - endpoint: https://api-2.example.com
          weight: 80
      healthCheck:
        path: /
        interval: 30s
        timeout: 10s
middlewares:
  - name: rate-limit
    type: rateLimit
    rule:
      unit: minute
      requestsPerUnit: 20
      banAfter: 5
      banDuration: 5m
  - name: basic-auth
    type: basicAuth
    paths: ["/admin","/docs","/openapi"]
    rule:
      realm: Restricted
      forwardUsername: true
      users:
        - username: admin
          password: $2y$05$TIx7l8sJWvMFXw4n0GbkQuOhemPQOormacQC4W1p28TOVzJtx.XpO # bcrypt hash for 'admin'
        - username: user
          password: password
certManager:
  acme:
    ## Uncomment email to enable Let's Encrypt
    # email: [email protected] # Email for ACME registration
    storageFile: /etc/letsencrypt/acme.json

compose.yaml

services:
  goma-gateway:
    image: jkaninda/goma-gateway
    command: -c /etc/goma/config.yaml
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./config:/etc/goma/
      - ./letsencrypt:/etc/letsencrypt

  api-example:
    image: jkaninda/okapi-example

Visit http://localhost/docs to see the documentation

---

8. Goma Admin and Docker Provider

Goma Gateway intentionally does not include a built-in Docker provider or user interface in order to remain lightweight, modular, and focused on its role as a data plane.

These capabilities are provided by Goma Admin, which acts as the control plane and includes native support for a Docker provider. This allows automatic generation of gateway configuration from container labels.

---

Goma Admin

Goma Admin is a web-based control plane for managing Goma Gateway configurations.

It provides a structured and user-friendly interface to define routes, middleware, and TLS settings without requiring manual editing of YAML configuration files.

Key Features

• Multi-instance management
• File & HTTP provider integration
• Docker-based service discovery
• Import / Export of configurations
• API key management
• Metrics & monitoring (Prometheus)
• OAuth2 integration (Keycloak, Authentik, Gitea)
• Audit logs (configuration history)
• Git synchronization (bi-directional)

---

Screenshots

Dashboard

Dashboard (Dark Mode)

---

Goma Docker Provider

When deploying services with Docker Compose or Docker Swarm, the Goma Docker Provider automatically generates gateway configuration from container labels.

This model is similar to Traefik, where routing rules, services, and middleware are defined directly on containers through labels.

Example: docker-compose

services:
  # Goma Gateway - Data Plane
  goma-gateway:
    image: jkaninda/goma-gateway:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./:/etc/goma
      - providers:/etc/goma/providers
    environment:
      GOMA_LOG_LEVEL: info
      GOMA_ENTRYPOINT_WEB_ADDRESS: :80
      GOMA_ENTRYPOINT_WEB_SECURE_ADDRESS: :443
      GOMA_FILE_PROVIDER_ENABLED: true
      GOMA_FILE_PROVIDER_WATCH: true
      GOMA_FILE_PROVIDER_DIRECTORY: /etc/goma/providers/default # Default instance
    networks:
      - goma-net

  # Goma Admin - Control Plane
  goma-admin:
    image: jkaninda/goma-admin:latest
    labels:
      - "goma.enable=false"
      - "goma.port=9000"
      - "goma.hosts=goma-admin.example.com"
    ports:
      - "9000:9000"
    environment:
      GOMA_DB_URL: postgresql://goma:goma@goma-postgres:5432/goma?sslmode=disable
      GOMA_ENVIRONMENT: development
      GOMA_PROVIDERS_DIR: /etc/goma/providers
      GOMA_DOCKER_ENABLED: true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - providers:/etc/goma/providers
    depends_on:
      goma-postgres:
        condition: service_healthy
    restart: unless-stopped

  goma-postgres:
    image: postgres:17-alpine
    container_name: goma-admin-postgres
    environment:
      POSTGRES_USER: goma
      POSTGRES_PASSWORD: goma
      POSTGRES_DB: goma
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U goma"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Example service exposed via Goma
  web-service:
    image: jkaninda/okapi-example
    labels:
      - "goma.enable=true"
      - "goma.port=8080"
      - "goma.hosts=example.com,www.example.com"
    networks:
      - goma-net

volumes:
  providers: {}
  postgres_data: {}

networks:
  goma-net:
    driver: bridge

---

References

• Goma Admin: https://github.com/jkaninda/goma-admin
• Goma Docker Provider: https://github.com/jkaninda/goma-docker-provider

---

9. Kubernetes deployment

Basic Deployment

kubectl apply -f https://raw.githubusercontent.com/jkaninda/goma-gateway/main/examples/k8s-basic-deployment.yaml

10. HTTP API Provider (External)

The Goma HTTP Provider exposes a REST API for managing routes, middleware, and gateway configuration dynamically.

It’s ideal for:

• Control planes
• Automation workflows
• Internal platform tools

👉 See: Goma HTTP Provider

11. Grafana Dashboard

Goma 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.

A prebuilt Grafana dashboard is available to visualize metrics from Goma Gateway.

You can import it using dashboard ID: 23799

Dashboard Preview

12. Production Deployment Guide

For production deployments, use the example from the link below:

production-deployment.

---

Supported Systems

• Linux
• MacOS
• Windows

Please download the binary from the release page.

Init configs:

./goma config init --output config.yml

To run

./goma server --config config.yml

---

Deployment

• Docker
• Kubernetes

Contributing

The Goma Gateway project welcomes all contributors. We appreciate your help!

🌟 Star History

⭐ If you find Goma Gateway useful, please consider giving it a star on GitHub!

Give a Star! ⭐

If this project helped you, do not skip on giving it a star. Thanks!

---

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Copyright

Copyright (c) 2024–2025 Jonas Kaninda and contributors

Built with ❤️ for the developer community