Skip to content

Hermes Gateway Configuration Reference

Configure Hermes Gateway using JSON/YAML files or environment variables.

Environment variables, often used with Docker, are stored in a .env file at the project's root. For production deployments, use configuration files to keep settings under version control.

Both methods follow the same naming conventions, making it easy to switch between them:

redis:
  state:
    enabled: true
    host: 127.0.0.1

corresponds to

REDIS_STATE_ENABLED=true
REDIS_STATE_HOST=127.0.0.1

Configuration Sections

Environment variables override values set in the configuration file.

Upstream Database

The upstream is the real database that Hermes Gateway proxies traffic to.

Note: If you are using passthrough authentication, make sure the upstream database is configured to allow plaintext passwords. See the MySQL documentation for more information.

Replication Stream

The replication stream is one of two ways Hermes Gateway can capture data changes.

In Replication Stream mode, the service listens passively to the replication stream without interfering with the application or the upstream database. If only the replication stream is enabled, Hermes Gateway will not process reads or gather usage metrics.

server_id is the MySQL replication server ID used to identify Hermes Gateway in the replication stream.

flavor is the database backend — either mysql or mariadb.

Upstream Database Configuration

The upstream database connection is configured under the upstream section:

upstream:
  host: "127.0.0.1"

The HOST, PORT, DATABASE, USER, and PASS fields control the upstream connection:

UPSTREAM_HOST=172.17.0.1
UPSTREAM_PORT=3306
UPSTREAM_DATABASE=mydatabasename
UPSTREAM_USER=user
UPSTREAM_PASS=pass

Server Configuration

The server configuration controls Hermes Gateway's frontend listener — how it is exposed to your application.

Uses the SERVER_ prefix and server: in the YAML file:

SERVER_LISTEN_PORT=3307
SERVER_READ_TIMEOUT_SEC=300
SERVER_WRITE_TIMEOUT_SEC=300
SERVER_CUSTOM_VERSION_STRING=8.0.33-hermes-gateway

Custom Version String

The custom version string is advertised to connecting clients as the server version. This is useful for identifying Hermes Gateway connections in your application logs, or for forcing compatibility with applications that require a specific MySQL version string. The actual upstream database can be running any version independently. This is useful to connect legacy applications that require a specific MySQL version string, while still benefiting from newer engines running upstream.

"custom_version_string": "8.0.33-hermes-gateway"

Metrics Configuration

Hermes Gateway can expose Prometheus metrics for integration with your existing monitoring stack. Configure the path and port to match your infrastructure:

metrics:
  enabled: true
  listen_port: 2112
  listen_path: /metrics

Logging Configuration

Logging controls the verbosity and output format of Hermes Gateway's logs. The service uses the Uber Zap framework for efficient, structured logging.

log:
  # Log level: debug, info, warn, error, fatal (default: warn)
  level: "info"

  # Optional file path for log output (default: empty, logs to console)
  output: "/var/log/hermes-gateway.log"

  # Whether to use colored level names in console output (default: false)
  format_capital_color: true

Environment variables for logging:

# Optional path to write log output to a file
# If not specified (empty), logs are written to console
LOG_OUTPUT=/var/log/hermes-gateway.log

# Log level to filter messages
# Available values: debug, info, warn, error, fatal (default: warn)
# See: https://github.com/uber-go/zap/blob/master/level.go
LOG_LEVEL=info

# Enable colored log level names in console output (true|false)
# Default: false
LOG_FORMAT_CAPITAL_COLOR=true

Log level descriptions:

  • debug: Detailed information, including all queries and response stats
  • info: General information about operations, including queries and responses
  • warn: Warning conditions that might require attention
  • error: Error conditions that prevent normal operation
  • fatal: Critical conditions that require immediate attention

Redis Settings

Hermes Gateway can use Redis to extend its functionality — either as a query cache to reduce upstream database load, or as a PubSub system to stream change events to other services.

Redis as a Query Cache

When both CACHE_ENABLED and REDIS_STATE_ENABLED are set to true, Hermes Gateway uses Redis as a transparent query cache, delivering immediate performance gains and reducing pressure on the upstream database.

cache:
  enabled: true

redis:
  state:
    enabled: true
    host: "127.0.0.1"
    port: 6379
    pass: "your-redis-password"
    db: 0

Redis PubSub

Redis PubSub enables Hermes Gateway to publish database change events to downstream consumers — turning your database into a real-time event source without any application changes.

redis:
  pubsub:
    enabled: true
    db: 1

Authentication

Hermes Gateway supports multiple authentication methods to secure the frontend listener.

The default is passthru, which uses your existing upstream database credentials and requires no additional setup.

Available options:

  • none: No authentication required. Do not use in production.
  • lua: Authenticate via a Lua script — enables integration with external user stores (e.g., Vault-mounted secrets, LDAP).
  • passthru: Pass credentials through to the upstream database. Requires the upstream to allow plaintext passwords.
  • allowlist: Authenticate against a static list of users defined in users.txt.

For a full breakdown of each method, see the Security Guide.

Pass Through Authentication

passthru (or passthrough) forwards credentials to the upstream MySQL/MariaDB database, reusing your existing access controls.

The upstream database must be configured to allow plaintext passwords. See the MySQL documentation for details.

Allow List Authentication

Define a static list of allowed users and hashed passwords in users.txt, using : as a separator. Passwords are hashed using MySQL's PASSWORD() function.

username:*ANENCRYPTEDPASSWORDHASH*

For a hands-on walkthrough, see the User Authentication with Lua Script guide.

Minimal Configuration Example

# Hermes Gateway — minimal cache-only configuration

cache:
  enabled: true

auth:
  handler: "none"

lua:
  enabled: false

metrics:
  enabled: false

replication_stream:
  enabled: true

upstream:
  host: "172.17.0.1"
  port: 3306
  database: "database"
  user: "user"
  pass: "pass"

server:
  listen_port: 3307

log:
  level: "info"
  output: ""  # Console output
  format_capital_color: false