Configuration

The gateway is configured via a single YAML file (gateway.yaml). This document describes all available configuration options.

Configuration File Structure

gateway:
  host: "0.0.0.0"
  port: 8080
  features:
    - request_id
    - real_ip
    - logger

proxies:
  - id: "proxy-id"
    host: "example.com"
    target: "http://backend:3000"

apis:
  - id: "api-id"
    target: "https://api.example.com"

routes:
  - id: "route-id"
    path: "/api/v1/*"
    strip_prefix:
      enabled: true
      prefix: "/api/v1"
    security:
      auth:
        enabled: true
        type: "api_key"
        header: "X-Api-Key"
        path:
          include: []
          exclude: []
      waf:
        enabled: true
        methods: ["GET", "POST"]

Sections

Gateway

Global gateway configuration.

Field	Type	Description	Default
`host`	string	Host address to bind to	Required
`port`	integer	Port number	Required
`features`	array	Global middleware features	Required

Features

Available global features:

Feature	Description
`request_id`	Adds unique request ID to each request
`real_ip`	Determines real client IP from headers
`logger`	Logs all HTTP requests

Proxies

Virtual hosting configuration for host-based routing.

Field	Type	Description
`id`	string	Unique proxy identifier
`host`	string	Domain/host name to match
`target`	string	Backend URL to proxy to

APIs

Backend service definitions referenced by routes.

Field	Type	Description
`id`	string	Unique API identifier (referenced by routes)
`target`	string	Backend URL

Routes

Route definitions with security policies.

Field	Type	Description
`id`	string	Unique route identifier (must match API ID)
`path`	string	Chi route pattern (e.g., `/api/v1/*`)
`strip_prefix`	object	Prefix stripping configuration
`security`	object	Security policies (auth, WAF)

Strip Prefix

Field	Type	Description
`enabled`	boolean	Enable prefix stripping
`prefix`	string	Prefix to remove from path

Security

Authentication

Field	Type	Description
`enabled`	boolean	Enable authentication
`type`	string	Auth type (`api_key`, `session`, etc.)
`header`	string	Header name to validate
`path`	object	Path-based filtering

Auth Path Filtering

Field	Type	Description
`include`	array	Paths that require auth (empty = all)
`exclude`	array	Paths that skip auth

Include/Exclude Logic:

If include is set → only matching paths require auth
If include is empty → all paths require auth except exclude

Wildcards (*) are supported in path patterns.

WAF (Web Application Firewall)

Field	Type	Description
`enabled`	boolean	Enable WAF
`methods`	array	Allowed HTTP methods (`["*"]` for all)

Example Configurations

Public API (No Auth)

routes:
  - id: "public-api"
    path: "/public/*"
    strip_prefix:
      enabled: true
      prefix: "/public"
    security:
      auth:
        enabled: false
      waf:
        enabled: true
        methods: ["GET", "POST"]

Protected API with API Key

routes:
  - id: "protected-api"
    path: "/api/v1/*"
    strip_prefix:
      enabled: true
      prefix: "/api/v1"
    security:
      auth:
        enabled: true
        type: "api_key"
        header: "X-Api-Key"
      waf:
        enabled: true
        methods: ["*"]

Mixed Auth (Path-based)

routes:
  - id: "mixed-api"
    path: "/api/*"
    security:
      auth:
        enabled: true
        header: "Authorization"
        path:
          include: ["/api/admin/*", "/api/users/*/profile"]
          exclude: ["/api/health", "/api/public/*"]
      waf:
        enabled: true
        methods: ["*"]

Configuration Loading

The gateway loads configuration from a file path relative to the binary:

cfg, err := config.NewFileConfig("../gateway.yaml")

For Docker deployments, mount the config file:

volumes:
  - ./gateway.yaml:/app/gateway.yaml:ro

Configuration

On this page