____                       
  / ___| ___  _ __ ___   __ _ 
 | |  _ / _ \| '_ ` _ \ / _` |
 | |_| | (_) | | | | | | (_| |
  \____|\___/|_| |_| |_|\__,_|
  :: 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:

• Documentation: Documentation
• Source Code: Goma Gateway on GitHub
• Docker Image: jkaninda/goma-gateway
• HTTP Provider: Goma HTTP Provider
• Docker Provider: Goma Docker Provider

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.

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

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

• 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

• Zero-downtime config reloads
• Structured logging with configurable levels
• Prometheus/Grafana metrics
• Graceful error handling and backend failure interception

• 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

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

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

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

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

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

• Structured logging
• Prometheus metrics
• Grafana dashboards

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

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.

Before you begin, ensure you have:

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

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.

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

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.

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)

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

Goma Gateway exposes the following endpoints:

• Gateway health:

  • /readyz
  • /healthz

• Routes health:

  • /healthz/routes

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

Goma Gateway does not include a built-in Docker provider to remain lightweight and modular. If you deploy services using Docker Compose or Docker Swarm, the Goma Docker Provider automatically generates gateway configuration from container labels.

This approach will feel familiar if you’ve used Traefik: routing rules, services, and middleware are declared directly on containers.

A simple docker-compose setup:

services:
  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_EXTRA_CONFIG_DIR=/etc/goma/providers
      -  GOMA_EXTRA_CONFIG_WATCH=true
      -  GOMA_ENTRYPOINT_WEB_ADDRESS=[::]:80
      -  GOMA_ENTRYPOINT_WEB_SECURE_ADDRESS=[::]:443
    networks:
      - goma-net

  goma-provider:
    image: jkaninda/goma-docker-provider
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro # Required
      - providers:/etc/goma/providers
    environment:
      - GOMA_OUTPUT_DIR=/etc/goma/providers # Optional, default /etc/goma/providers
      - GOMA_ENABLE_SWARM=false # Enable Swarm mode, default false
    networks:
      - goma-net
  # Web Service - Minimal Configuration
  web-service:
    image: jkaninda/okapi-example
    labels:
      - "goma.enable=true" # Required to expose the service
      - "goma.port=8080"
      - "goma.hosts=example.com, www.example.com" # Optional
    networks:
      - goma-net
volumes:
  providers: {}
networks:
  goma-net:
    driver: bridge

👉 See: Goma Docker Provider

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

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

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

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

production-deployment.

• 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

• Docker
• Kubernetes

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

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

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

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

Copyright (c) 2024–2025 Jonas Kaninda and contributors

Built with ❤️ for the developer community