Skip to content

Installation Guide — Hermes Gateway Database Proxy

This guide covers how to install and run Hermes Gateway, a high-performance database proxy for MySQL. For configuration options, see the Config Guide.

Quick Start with Docker

Docker is the recommended way to deploy Hermes Gateway. Clone the repository and navigate to the deployments folder to get started:

git clone https://gitlab.k8s.appns.cloud/dfernandez/hermes-gateway.git
cd hermes-gateway/deployments

Or clone via SSH:

git clone ssh://git@gitlab.k8s.appns.cloud:10022/dfernandez/hermes-gateway.git

Makefiles are included to simplify common operations:

make help
make .env              # generate the .env configuration file
# Edit .env to point Hermes Gateway at your MySQL server
make start-proxy       # start the Hermes Gateway database proxy
make start-monitoring  # start the monitoring stack (optional)

Once running, Hermes Gateway will accept MySQL connections on the configured port — connect with any standard SQL client.

If you started the monitoring stack, Prometheus metrics are available at http://localhost:9090.

For console commands and query cache controls, see the Console Guide:

SHOW CACHE HELP;
SHOW CACHE STATS;

Pulling the Docker Image from the Public Registry

The Hermes Gateway Docker image is based on Debian Bullseye.

Public Registry: 

core.harbor.k8sprod.appns.cloud/hermes-gateway/hermes-gateway:v0.1.8

To pull a specific version:

docker pull core.harbor.k8sprod.appns.cloud/hermes-gateway/hermes-gateway:v0.0.4

Deploying Hermes Gateway with Helm

Hermes Gateway ships a Helm chart for Kubernetes deployments. The recommended approach is to start from the values template and customise it:

# Download the values template for your target version
helm show values oci://core.harbor.k8sprod.appns.cloud/hermes-gateway/charts/hermes-gateway --version v0.1.8 > values-v0.1.8.initial.yaml

# Create your customised config
cp values-v0.1.8.initial.yaml values-v0.1.8.yaml
nano values-v0.1.8.yaml

# Deploy Hermes Gateway to the 'hermes' namespace
helm upgrade --install hermes-gateway oci://core.harbor.k8sprod.appns.cloud/hermes-gateway/charts/hermes-gateway \
  --version v0.1.8 -f values-v0.1.8.yaml \
  -n hermes --create-namespace --force --wait

For a minimal deployment, you can pass upstream database settings directly on the command line:

helm upgrade --install hermes-gateway oci://core.harbor.k8sprod.appns.cloud/hermes-gateway/charts/hermes-gateway \
  --version v0.1.8 -n hermes --create-namespace --force --wait \
  --set config.upstream.host=mysql.mysql.svc.cluster.local \
  --set config.upstream.port=3306 \
  --set config.upstream.database=my_database \
  --set config.upstream.user=root \
  --set config.upstream.pass=123456

Local Development & Custom Builds

Hermes gateway is not open source at this time, but we welcome collaboration and contributions from our customers and partners. If you're interested in contributing or need a custom build, please contact us to discuss your requirements.

Private Registry Image

Private Registry: 

registry.gitlab.k8s.appns.cloud/dfernandez/hermes-gateway:latest

Development builds are available from our private registry. To obtain credentials and access the latest builds, please contact us. Login instructions are included in monitoring/Makefile — you'll need a GitLab user and token stored in .secrets, or log in to the Docker registry manually.