Skip to main content

MTE API Relay On-Premise Deployment

Introduction​

MTE API Relay is an end-to-end encryption system that protects HTTP traffic between server applications. It acts as a proxy server in front of your backend services, communicating with another API Relay instance to encode and decode all proxied traffic. This enables secure application-to-application communications using the Eclypses MTE encryption engine.

Below is a typical architecture where one server application communicates through an MTE API Relay container, which transmits proxied traffic to another API Relay that decodes and forwards the request to its target backend service:

Typical Use Case

Prerequisites​

Technical Requirements​

  • An existing backend service that accepts HTTP calls.
  • Docker installed and running on your system.
  • AWS CLI installed.

Skills and Knowledge​

  • Familiarity with Docker and/or Kubernetes.
  • General knowledge of container deployment models.

Credentials​

  • An AWS Access Key ID and AWS Secret Access Key provided by Eclypses to access the private container repository.

Deployment Options​

MTE API Relay is provided as a Docker image and can be deployed on-premise using:

  • Docker Run
  • Docker Compose
  • Kubernetes
  • Other container runtimes (e.g., Docker Swarm, Podman, K3s)

1. Configure AWS CLI Access​

Configure a new AWS CLI profile with the Eclypses-issued credentials:

aws configure --profile eclypses-customer-on-prem

When prompted:

  • AWS Access Key ID: Enter the ID provided by Eclypses.
  • AWS Secret Access Key: Enter the secret key provided.
  • Default region name: us-east-1
  • Default output format: json

2. Pull the Docker Image​

Authenticate Docker with the Eclypses ECR registry:

aws ecr get-login-password --region us-east-1 --profile eclypses-customer-on-prem \
  | docker login --username AWS \
  --password-stdin 321186633847.dkr.ecr.us-east-1.amazonaws.com

Then pull the image:

docker pull 321186633847.dkr.ecr.us-east-1.amazonaws.com/customer/on-prem/mte-api-relay:4.4.8

Server Configuration​

MTE API Relay is configured using environment variables.

Required Variables​

  • UPSTREAM – Upstream API or service URL.
  • CLIENT_ID_SECRET – Secret for signing client IDs (minimum 32 characters).
  • OUTBOUND_TOKEN – Token appended to requests to denote the intended outbound recipient.
  • REDIS_URL (recommended for production) – Redis cluster for maintaining session pairs across load-balanced containers.

Optional Variables​

  • PORT – Default: 8080.
  • DEBUG – Set to true to enable verbose logs (default: false).
  • HEADERS – Object of custom headers.
  • CORS_ORIGINS – Comma-separated list of allowed origins.
  • CORS_METHODS – Default: GET, POST, PUT, DELETE.

Minimal Example​

UPSTREAM='https://api.my-company.com'
CLIENT_ID_SECRET='2DkV4DDabehO8cifDktdF9elKJL0CKrk'
OUTBOUND_TOKEN='abcdefg1234567'

Full Example​

UPSTREAM='https://api.my-company.com'
CLIENT_ID_SECRET='2DkV4DDabehO8cifDktdF9elKJL0CKrk'
OUTBOUND_TOKEN='abcdefg1234567'
REDIS_URL='redis://10.0.1.230:6379'
PORT=3000
DEBUG=true
HEADERS='{"x-service-name":"mte-api-relay"}'
CORS_ORIGINS='https://www.my-company.com,https://dashboard.my-company.com'
CORS_METHODS='GET,POST,DELETE'

Deployment Steps​

Option A: Docker Run​

docker run --rm -it \
  --name mte-api-relay \
  -p 8080:8080 \
  -e UPSTREAM="<YOUR_BACKEND_URL>" \
  -e CLIENT_ID_SECRET="<YOUR_CLIENT_ID_SECRET>" \
  -e OUTBOUND_TOKEN="<YOUR_SECURE_OUTBOUND_ACCESS_TOKEN>" \
  -e REDIS_URL="<YOUR_REDIS_URL>" \
  321186633847.dkr.ecr.us-east-1.amazonaws.com/customer/on-prem/mte-api-relay:4.4.8

Option B: Docker Compose​

version: "3.8"

services:
  mte-api-relay:
    image: 321186633847.dkr.ecr.us-east-1.amazonaws.com/customer/on-prem/mte-api-relay:4.4.8
    ports:
      - "8080:8080"
    environment:
      - UPSTREAM=https://api.my-company.com
      - CLIENT_ID_SECRET=YOUR_32_PLUS_CHARACTER_CLIENT_ID_SECRET
      - OUTBOUND_TOKEN=YOUR_SECURE_OUTBOUND_ACCESS_TOKEN
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis

  redis:
    image: "redis:alpine"

Option C: Kubernetes​

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mte-api-relay-deployment
spec:
  replicas: 2
  selector:
    matchLabels:
      app: mte-api-relay
  template:
    metadata:
      labels:
        app: mte-api-relay
    spec:
      containers:
        - name: mte-api-relay
          image: 321186633847.dkr.ecr.us-east-1.amazonaws.com/customer/on-prem/mte-api-relay:4.4.8
          ports:
            - containerPort: 8080
          env:
            - name: UPSTREAM
              value: "<YOUR_BACKEND_URL>"
            - name: CLIENT_ID_SECRET
              value: "<YOUR_CLIENT_ID_SECRET>"
            - name: OUTBOUND_TOKEN
              value: "<YOUR_SECURE_OUTBOUND_ACCESS_TOKEN>"
            - name: REDIS_URL
              value: "redis://my-redis-service:6379"
---
apiVersion: v1
kind: Service
metadata:
  name: mte-api-relay-service
spec:
  type: LoadBalancer
  selector:
    app: mte-api-relay
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8080
kubectl apply -f mte-api-relay-deployment.yaml
kubectl get all
kubectl delete -f mte-api-relay-deployment.yaml

Testing & Health Checks​

  • Monitor container logs for startup messages:

    • MTE instantiated successfully.
    • Server listening at http://[0.0.0.0]:8080

  • Test echo route:

curl http://<MTE_API_RELAY_HOST_OR_IP>:<PORT>/api/mte-echo?msg=test

Expected response:

{
  "echo": "test",
  "time": "<timestamp>"
}

Troubleshooting​

  1. Invalid Configuration
    • Check logs for missing/invalid environment variables.
  2. Relay unreachable
    • Verify firewall, networking, or Kubernetes service configuration.
  3. Redis connection issues
    • Ensure REDIS_URL is reachable in your environment.
  4. Cannot Reach Upstream Service
    • Verify the container can resolve and connect to the target host.

Security​

  • No sensitive data is stored in the container.
  • No root privileges required.
  • Recommended to deploy close to the upstream service to minimize exposure of unencrypted traffic.

Costs​

Private infrastructure costs (VMs, storage, networking, Redis clusters) are customer-managed. No AWS charges are incurred for on-premise usage.

Maintenance​

Routine Updates​

  • Updated container images are distributed through Eclypses.

Fault Recovery​

  • Relaunch the Relay container; paired API Relays will automatically re-establish secure communication.

Key/Variable Rotation Recommendations​

  • Rotate the CLIENT_ID_SECRET and OUTBOUND_TOKEN every 90 days as per security best practices.

Support​

For assistance, contact Eclypses Support:
📧 customer_support@eclypses.com
🕒 Monday–Friday, 8:00 AM–5:00 PM MST (excluding holidays)