MTE API Relay On-Premise Deployment

Introduction

The MTE API Relay is a NodeJS application that encodes and proxies HTTP payloads to another MTE API Relay, which then decodes and forwards the request to the final upstream API service. This creates a secure, end-to-end encrypted tunnel for your API traffic, protecting data in transit across networks.

This guide provides instructions for customers to pull the MTE API Relay Docker image from our private Amazon ECR repository and deploy it in an on-premise environment using Docker, Docker Swarm, Kubernetes, or other container runtimes.

Prerequisites

Technical Requirements

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

Credentials

• You must have an AWS Access Key ID and AWS Secret Access Key provided by Eclypses to access the private container repository.

Step 1: Configure AWS CLI Access

You will need to configure a new AWS CLI profile using the credentials we provided. This keeps your access separate from any other AWS accounts you might have.

1. Open your terminal or command prompt.

2. Run the following command to start the configuration process:

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

3. The CLI will prompt you for the following information. Use the values provided to you by Eclypses.

   • AWS Access Key ID: Paste the Access Key ID.
   • AWS Secret Access Key: Paste the Secret Access Key.
   • Default region name: Enter us-east-1.
   • Default output format: Enter json.

Step 2: Pull the Docker Image

Next, use your configured AWS profile to authenticate Docker with our Amazon ECR repository and pull the image.

1. Run the following command to retrieve an authentication token and log Docker in.

   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

   A Login Succeeded message confirms a successful authentication.

2. Pull the MTE API Relay image to your local machine.

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

Note: Once pulled, you may want to re-tag this image and push it to your own internal container registry for easier distribution within your infrastructure.

Step 3: Server Configuration

Configure the MTE API Relay using the following environment variables:

Required Configuration

• UPSTREAM
  • The URL of the upstream API service where decoded requests will be proxied.
• CLIENT_ID_SECRET
  • A secret string (32+ characters recommended) used to sign the x-mte-client-id header for sender validation.
• OUTBOUND_TOKEN
  • A secret token that must be present in the x-mte-outbound-token header of incoming requests to authorize proxying.
• REDIS_URL
  • The connection URL for your Redis instance (e.g., redis://<host>:<port>). In load-balanced environments, a shared Redis cache is required for MTE state management between container instances.

Optional Configuration

• PORT
  • The port on which the MTE API Relay will listen for incoming traffic. Default: 8080.
• DEBUG
  • Set to true to enable verbose debug logging for troubleshooting. Default: false.
• HEADERS
  • A JSON string of headers to be added to all proxied requests/responses. Default: {}.

Step 4: Deploy MTE API Relay

MTE API Relay is configured via environment variables. Below are examples for running it with Docker and Kubernetes.

Docker Run Example

docker run --rm -it \
  --name mte-api-relay \
  -p 8080:8080 \
  -e UPSTREAM="https://api.my-company.com" \
  -e CLIENT_ID_SECRET="YOUR_32_PLUS_CHARACTER_CLIENT_ID_SECRET" \
  -e OUTBOUND_TOKEN="YOUR_SECURE_OUTBOUND_ACCESS_TOKEN" \
  -e REDIS_URL="redis://your-redis-host:6379" \
  321186633847.dkr.ecr.us-east-1.amazonaws.com/customer/on-prem/mte-api-relay:4.4.7

Docker Compose Example

# docker-compose.yml
version: "3.8"

services:
  mte-api-relay:
    image: 321186633847.dkr.ecr.us-east-1.amazonaws.com/customer/on-prem/mte-api-relay:4.4.7
    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"

Kubernetes Deployment Example

# mte-api-relay-deployment.yaml
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.7
          ports:
            - containerPort: 8080
          env:
            - name: UPSTREAM
              value: "https://api.my-company.com"
            - name: CLIENT_ID_SECRET
              value: "YOUR_32_PLUS_CHARACTER_CLIENT_ID_SECRET"
            - name: OUTBOUND_TOKEN
              value: "YOUR_SECURE_OUTBOUND_ACCESS_TOKEN"
            - name: REDIS_URL
              value: "redis://your-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

Step 5: Usage Guide

To protect traffic, your client application must send requests to the MTE API Relay instead of the final destination. The request must include two special headers.

• x-mte-outbound-token: Contains the value of your OUTBOUND_TOKEN environment variable.
• x-mte-upstream: The URL of the receiving MTE API Relay, which will decode the request.

The first relay encrypts the payload and forwards it to the second relay specified in x-mte-upstream. The second relay decrypts it and sends it to its configured UPSTREAM service.

Example curl Request

curl --location 'http://<RELAY_SERVER_1_URL>/api/login' \
--header 'x-mte-outbound-token: YOUR_SECURE_OUTBOUND_ACCESS_TOKEN' \
--header 'x-mte-upstream: http://<RELAY_SERVER_2_URL>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "jim.halpert@example.com",
    "password": "P@ssw0rd!"
}'

Step 6: Testing and Health Checks

Health Check Route

Use the /api/mte-echo route to verify the service is running.

curl http://<MTE_RELAY_HOST_OR_IP>:<PORT>/api/mte-echo

A successful response will be a JSON payload with a timestamp:

{
  "echo": "test",
  "time": "2025-08-14T20:00:00.000Z"
}

Troubleshooting

• Review Container Logs: Most issues can be diagnosed by checking the container's logs.
  • docker logs mte-api-relay
  • kubectl logs -l app=mte-api-relay
• ZodError on Startup: This is a configuration validation error. The log will indicate which required environment variable is missing or invalid.
• Cannot Reach Upstream Service: Ensure the MTE API Relay container can resolve and connect to the UPSTREAM URL. Check firewalls and container network policies.
• Cannot Reach Redis: Verify the REDIS_URL is correct and the container has network access to your Redis instance.

Support

The Eclypses support center is available from 8:00 am to 5:00 pm MST, Monday through Friday. Please direct all inquiries to: customer_support@eclypses.com