Skip to content

Hermes Gateway Docker Quickstart — Database Proxy Up in Minutes

Get Hermes Gateway, the drop-in MySQL database proxy, running locally with Docker in just a few commands.

Starting Hermes Gateway

  1. Copy the default environment variables from .env.dist to .env and set your local configuration. For full details, see the Configuration Guide.
  2. Run cd deployments; make start-proxy to spin up a minimal environment, including the required Redis and MySQL instances.

Docker Image

The Hermes Gateway public image is available at:

core.harbor.k8sprod.appns.cloud/dbproxy/mysql-proxy:v0.1.8
# or 
core.harbor.k8sprod.appns.cloud/hermes-gateway/hermes-gateway:v0.1.8

docker pull core.harbor.k8sprod.appns.cloud/dbproxy/mysql-proxy:v0.1.8
# or
docker pull core.harbor.k8sprod.appns.cloud/hermes-gateway/hermes-gateway:v0.1.8

A ready-to-use example Docker Compose file is available at deployments/docker-compose.proxy-demo.yml.

Requirements:

  • .env file with environment variables (see .env.dist for reference)
  • lua/ directory with example handlers
  • demo-data/init.sql file with database initialisation

Accessing Hermes Gateway Services

Hermes Gateway exposes both a MySQL-compatible SQL endpoint and a Prometheus metrics endpoint. For full details on ports and connection strings, see the Access Guide.

Configuration

Follow the Configuration Guide to connect Hermes Gateway to your upstream MySQL or MariaDB database, enable query caching, and tune performance settings.

Building from Source

To build for development purposes, check the Development Guide. To deploy a pre-built image, go straight to the Installation Guide.

Integrating Hermes Gateway into Your Own Stack

The core Docker Compose service that runs the Hermes Gateway database proxy is straightforward to embed in an existing stack. For port configuration see the Access Guide; all other settings are controlled via a config file or equivalent environment variables — see the Configuration Guide.

services:
  hermes-gateway:
    image: core.harbor.k8sprod.appns.cloud/dbproxy/mysql-proxy:v0.1.8
    stop_grace_period: 1s
    restart: "no"
    env_file:
      - ./.env
    ports:
      - 3307:3307
      - 2112:2112
    depends_on:
      redis:
        condition: service_healthy
      mysql:
        condition: service_healthy
    volumes:
      - ./.env:/.env:ro
      - ./lua:/lua:ro
    healthcheck:
      test: ["CMD", "/bin/true"]
      interval: 1s
      timeout: 1s
      retries: 50
      start_period: 0s