jkaninda/goma-docker-provider

By jkaninda

•Updated 8 months ago

A Docker provider for Goma Gateway, a declarative API Gateway Management & Reverse proxy

Image

Developer tools

2.2K

Overview Tags

jkaninda/goma-docker-provider repository overview

⁠Goma Docker Provider

The Goma Docker Provider is a dynamic configuration provider for Goma Gateway. It automatically discovers Docker containers via labels and generates Goma Gateway route configurations without manual YAML editing.

It’s ideal for Docker-based and Docker Compose deployments where services should self-register routes declaratively.

Docker Image Size (latest by date) Docker Pulls

⁠How It Works

The provider:

Scans running containers for the label goma.enable=true
Converts container labels into Goma Gateway routes
Writes the generated routes to a YAML file
Supports single-route and multi-route containers
Periodically polls Docker to keep routes in sync

⁠Startup Flow & Configuration Sync

This diagram shows how Goma Gateway, Goma Docker Provider, and Docker services interact at runtime.

⁠Startup Flow Diagram

flowchart LR
    A[Docker Engine] -->|List containers & labels| B[Goma Docker Provider]

    B -->|Generate route YAML| C[/Routes Directory<br/>/etc/goma/providers/]

    C -->|Watch & load routes| D[Goma Gateway]

    D -->|Expose routes| E[Incoming Traffic]

    subgraph Docker Services
        A
    end

    subgraph Goma
        B
        C
        D
    end

⁠Links

Gateway: Goma Gateway on GitHub⁠
Source Code: goma-docker-provider⁠
Docker Image: jkaninda/goma-docker-provider⁠

⁠Defaults

Setting	Default
Output file	`goma-docker-provider.yaml`
Output directory	`/etc/goma/providers`
Poll interval	`10s`

All defaults can be overridden via environment variables.

⁠Minimal Configuration

services:
  api-service:
    image: your-api:latest
    labels:
      # Core
      - "goma.enable=true"
      - "goma.port=8000"
      - "goma.hosts=api.example.com,api.local"

⁠Single-Route Configuration (Basic)

A container exposing one route can use flat goma.* labels.

services:
  api-service:
    image: your-api:latest
    labels:
      # Core
      - "goma.enable=true"
      - "goma.name=api"
      - "goma.path=/api"
      - "goma.port=8000"
      - "goma.rewrite=/" # Rewrite /api → /
      - "goma.priority=100"

      # Hosts & Methods
      - "goma.hosts=api.example.com,api.local"
      - "goma.methods=GET,POST,PUT,DELETE"

      # Health Check
      - "goma.health_check.path=/health"
      - "goma.health_check.interval=30s"
      - "goma.health_check.timeout=5s"
      - "goma.health_check.healthy_statuses=200,204"

      # Security
      - "goma.security.forward_host_headers=true"
      - "goma.security.enable_exploit_protection=true"
      - "goma.security.tls.insecure_skip_verify=false"

      # Features
      - "goma.middlewares=jwt-auth,rate-limit"
      - "goma.disable_metrics=false"

⁠Multi-Route Configuration

If a container exposes multiple ports or paths, use the goma.routes.{routeName}.* pattern.

services:
  multi-service:
    image: your-service:latest
    labels:
      - "goma.enable=true"

      # Route: API
      - "goma.routes.api.path=/api"
      - "goma.routes.api.port=8000"
      - "goma.routes.api.methods=GET,POST,PUT,DELETE"
      - "goma.routes.api.health_check.path=/health"
      - "goma.routes.api.health_check.interval=30s"
      - "goma.routes.api.security.forward_host_headers=true"

      # Route: Metrics
      - "goma.routes.metrics.path=/metrics"
      - "goma.routes.metrics.port=9090"
      - "goma.routes.metrics.methods=GET"
      - "goma.routes.metrics.disable_metrics=true"

      # Route: Admin
      - "goma.routes.admin.path=/admin"
      - "goma.routes.admin.port=8081"
      - "goma.routes.admin.hosts=admin.example.com"
      - "goma.routes.admin.security.enable_exploit_protection=true"
      - "goma.routes.admin.security.tls.insecure_skip_verify=false"

⁠Docker Labels Reference

⁠Core Route Labels

Label	Description	Example
`goma.enable`	Enable route discovery	`true`
`goma.name`	Route name	`api`
`goma.path`	Public route path	`/api`
`goma.port`	Container port	`8080`
`goma.scheme`	Container scheme	`http`
`goma.rewrite`	Rewrite path	`/`
`goma.priority`	Route priority	`100`
`goma.enabled`	Enable/disable route	`true`

⁠Hosts & Methods

Label	Description
`goma.hosts`	Allowed hostnames
`goma.methods`	Allowed HTTP methods

⁠Health Check

Label	Description
`goma.health_check.path`	Health endpoint
`goma.health_check.interval`	Check interval
`goma.health_check.timeout`	Timeout
`goma.health_check.healthy_statuses`	Valid HTTP statuses

⁠Security

Label	Description
`goma.security.forward_host_headers`	Forward original Host header
`goma.security.enable_exploit_protection`	Enable exploit protection
`goma.security.tls.insecure_skip_verify`	Skip TLS verification

⁠Features & Observability

Label	Description
`goma.middlewares`	Attached middlewares
`goma.disable_metrics`	Disable metrics for route

⁠Multi-Route Pattern

Pattern	Description
`goma.routes.{name}.path`	Route path
`goma.routes.{name}.port`	Route port
`goma.routes.{name}.scheme`	Route scheme
`goma.routes.{name}.methods`	Allowed methods
`goma.routes.{name}.hosts`	Hosts
`goma.routes.{name}.health_check.*`	Health check
`goma.routes.{name}.security.*`	Security options

⁠Environment Variables

Variable	Description	Default
`GOMA_OUTPUT_DIR`	Output directory for routes	`/etc/goma/providers`
`GOMA_POLL_INTERVAL`	Docker polling interval	`10s`
`GOMA_ENABLE_SWARM`	Enable Docker Swarm mode	`false`

⁠Example Deployment

⁠1. Goma Gateway Configuration

Create goma.yml:

version: "2"

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

  log:
    level: info
  providers:
    file:
      enabled: true
      directory: /etc/goma/providers
      watch: true
  monitoring:
    enableMetrics: true
    enableLiveness: true

  # extraConfig:
  #   directory: /etc/goma/providers
  #   watch: true

  routes: []

middlewares:
  - name: basic-auth
    type: basicAuth
    paths: ["/.*"]
    rule:
      realm: Restricted
      users:
        - username: admin
          password: $2y$05$TIx7l8sJWvMFXw4n0GbkQuOhemPQOormacQC4W1p28TOVzJtx.XpO

certManager:
  provider: acme

⁠2. Docker Compose

services:
  goma-gateway:
    image: jkaninda/goma-gateway:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./config:/etc/goma
      - providers:/etc/goma/providers
    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"
      - "goma.port=8080"
      - "goma.hosts=example.com, www.example.com"
    networks:
      - goma-net
volumes:
  providers: {}
networks:
  goma-net:
    driver: bridge

⁠Required Goma Gateway Configuration

The Goma Docker Provider only generates route files. For these routes to be loaded and applied, Goma Gateway must be configured to read and watch the generated directory.

You must configure ONE (and only one) of the following options:

Extra Config (simple, legacy-compatible)
File Provider (recommended)

⁠Option 1: Extra Config (Simple)

Use this option if you want a minimal setup.

extraConfig:
  directory: /etc/goma/providers
  watch: true

⁠Option 2: File Provider (Recommended)

This is the preferred approach, especially when using multiple providers.

providers:
  file:
    enabled: true
    directory: /etc/goma/providers
    watch: true

⁠License

MIT License — free to use, modify, and distribute.

⁠© Copyright

Tag summary

Recent tags

Content type

Image

Digest

sha256:164a6b56d…

Size

11.9 MB

Last updated

8 months ago

docker pull jkaninda/goma-docker-provider