MTE Relay Server on Oracle Cloud Infrastructure

Introduction

MTE Relay Server is an end to end encryption system that protects all network requests with next generation application data security. It acts as a proxy server in front of your backend, communicating with an MTE Relay Client to encode and decode all network traffic. The server is highly customizable and supports integration with other services through custom adapters.

Below is a typical architecture where a client application communicates with an MTE Relay Server, which then proxies decoded traffic to backend services:

info

MTE Relay Servers can only communicate with MTE Relay Clients. An MTE API Relay cannot communicate with an MTE Relay Server or an MTE Relay Client SDK. MTE Relay Servers are strictly for client to server communications.

On Oracle Cloud Infrastructure (OCI), the same Docker image used for on premise deployments can be launched two ways:

• OCI Container Instances, Oracle's managed container runtime for running containers without managing servers or a cluster.
• Oracle Kubernetes Engine (OKE), Oracle's managed Kubernetes service, for orchestrated, scalable deployments.

Both options pull the image from the Oracle Cloud Infrastructure Registry (OCIR) in your own tenancy. The first sections below cover pulling the image from Eclypses and pushing it into OCIR; after that, follow Option A for Container Instances or Option B for OKE.

---

Prerequisites

Technical Requirements

• A web or mobile application project that communicates with a backend API over HTTP.
  • Our demo app is available on GitHub: MTE Relay Demos.
• An OCI tenancy with permission to use the Container Registry (OCIR) and either Container Instances or an OKE cluster.
• Docker installed and running on your system.
• AWS CLI installed (used only to pull the image from the Eclypses registry).
• OCI CLI installed (optional for the console workflow, required for the CLI examples).
• kubectl installed if deploying to OKE.

Skills and Knowledge

• Familiarity with Docker and/or Kubernetes.
• Basic knowledge of OCI networking (VCNs, subnets, security lists).

Credentials

• An AWS Access Key ID and AWS Secret Access Key provided by Eclypses to access the private container repository.
• An OCI auth token for logging Docker into OCIR (created below).

---

Step 1: Pull the Image from Eclypses

Configure AWS CLI Access

You must configure a new AWS CLI profile using the credentials provided by Eclypses.

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

Pull the Docker Image

Authenticate Docker with the Eclypses ECR repository:

bash

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

PowerShell

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-relay-server:4.7.0

---

Step 2: Push the Image to OCIR

OCI services pull images most reliably from the Container Registry in your own tenancy. Authorization tokens for the Eclypses registry expire after 12 hours, so pointing Container Instances or OKE directly at the Eclypses repository is not practical. Instead, pull the image once and push it into OCIR, then deploy from there.

1. Create an Auth Token

In the OCI Console, open your profile menu, select My profile, then select Auth tokens and generate a new token. Copy the value immediately; it is only shown once. Store it in a password manager.

2. Find Your Tenancy Namespace

The tenancy namespace (also called the Object Storage namespace) is part of every OCIR image path. Retrieve it with the OCI CLI:

oci os ns get

It is also shown in the console under Tenancy details.

3. Log Docker into OCIR

OCIR registry hostnames follow the pattern <region-key>.ocir.io, for example iad.ocir.io for US East (Ashburn) or phx.ocir.io for US West (Phoenix). Log in using your tenancy namespace and user name, with the auth token as the password:

docker login <region-key>.ocir.io

• Username: <tenancy-namespace>/<username>
  • Example: mytenancy/first.last@company.com
  • Federated users include the identity provider: <tenancy-namespace>/oracleidentitycloudservice/<username>
• Password: the auth token created above.

4. Tag and Push

docker tag 321186633847.dkr.ecr.us-east-1.amazonaws.com/customer/on-prem/mte-relay-server:4.7.0 <region-key>.ocir.io/<tenancy-namespace>/mte-relay-server:4.7.0

docker push <region-key>.ocir.io/<tenancy-namespace>/mte-relay-server:4.7.0

note

If the mte-relay-server repository does not already exist in OCIR, the push creates it automatically in your root compartment (when your user has permission to manage repositories). You can also create the repository first under Developer Services, Container Registry, and choose whether it is private (recommended) or public.

---

Server Configuration

MTE Relay Server is configured using environment variables.

Using a DOMAIN_MAP (Recommended)

Interactive Builder

Use the DOMAIN_MAP Builder tool to configure your domains visually, validate your settings, and copy a DOMAIN_MAP value that is ready to use, with no manual JSON editing required.

DOMAIN_MAP is a JSON object keyed by the Host header that arrives with each request.
The value for each key is a settings object that tells the proxy how to process the request.

Settings

Field	Type	Purpose
upstream	string	Full URL (http://localhost:8080, https://api.internal)
pass_through_routes	string[]	Paths that use standard HTTP proxy, without MTE encryption
client_id_secret	string	Legacy shared secret used by some auth layers
cors_origins	string[]	List of allowed CORS origins for preflight requests
cors_methods	string[]	List of allowed CORS methods for preflight requests
headers	string	A JSON object of additional headers to add to proxied requests

Example: requests with Host header relay.example.com are decrypted and forwarded to http://internal-service. The /health route is proxied without MTE encoding/decoding.

{
  "relay.example.com": {
    "upstream": "http://internal-service",
    "client_id_secret": "8KeJmtuKweUhymNJmGHvGMrJCUtHxhQG",
    "pass_through_routes": ["/health"],
    "cors_origins": ["https://app.company.com"]
  }
}

Export as one line env var:

export DOMAIN_MAP='{ "relay.example.com": { "upstream": "http://internal-service", "client_id_secret": "8KeJmtuKweUhymNJmGHvGMrJCUtHxhQG", "pass_through_routes": ["/health"], "cors_origins": ["https://app.company.com"] } }'

Host Matching

MTE Relay Server performs an exact match against the Host header (case insensitive).
If an exact match is not found, it checks for a wildcard ("*").
If no match is found, the request is rejected with 404.

The key in DOMAIN_MAP must therefore match the exact hostname clients use to reach the relay: the load balancer DNS name, the public IP with port, or your custom domain. A wildcard "*" key matches any host and is convenient while testing.

Using individual Environment Variables (Legacy)

Using these environment variables will result in the MTE Relay Server being configured to only handle a single domain. This method is deprecated in favor of using the DOMAIN_MAP variable. If both are provided, DOMAIN_MAP will take precedence.

Example:

• UPSTREAM - Upstream API or service URL.
• CLIENT_ID_SECRET - Secret for signing client IDs (minimum 32 characters).
• PASS_THROUGH_ROUTES - Comma separated list of routes proxied without encoding/decoding.
• CORS_ORIGINS - Comma separated list of allowed origins.
• CORS_METHODS - Comma separated list of allowed methods. Default: GET, POST, PUT, DELETE.

UPSTREAM='https://api.my-company.com'
CLIENT_ID_SECRET='2DkV4DDabehO8cifDktdF9elKJL0CKrk'
PASS_THROUGH_ROUTES='/health,/version'

Additional Environment Variables

• PORT - Default: 8080.
• LOG_LEVEL - One of trace, debug, info, warning, error, panic, disabled. Default: info.
• REDIS_URL - Connection string for a shared Redis instance. Required when running more than one relay replica.

---

Deployment Steps

Option A: OCI Container Instances

Container Instances run containers directly on managed infrastructure with no cluster, virtual machine, or control plane to operate. This is the fastest way to stand up a relay on OCI and is well suited to evaluations and lower traffic workloads.

1. Create the Container Instance

In the OCI Console, go to Developer Services, Containers & Artifacts, Container Instances, and select Create container instance.

• Name and compartment: for example mte-relay.
• Shape: CI.Standard.E4.Flex with 1 OCPU and 4 GB of memory is a good starting point.
• Networking: select your VCN and subnet. For a quick evaluation, use a public subnet and keep Assign a public IPv4 address checked. For production, place the instance in a private subnet behind an OCI Load Balancer.

2. Configure the Container

• Image: select OCIR and browse to <region-key>.ocir.io/<tenancy-namespace>/mte-relay-server:4.7.0. If the repository is private, provide the OCIR credentials (<tenancy-namespace>/<username> and your auth token) when prompted.
• Environment variables: add DOMAIN_MAP with your configuration as a single line of JSON. While testing against the public IP, a wildcard key is easiest:

{ "*": { "upstream": "__YOUR_UPSTREAM_URL__", "client_id_secret": "__YOUR_CLIENT_ID_SECRET__", "cors_origins": ["__YOUR_CORS_ORIGINS__"] } }

Then select Create. The instance typically becomes active in under a minute.

3. Open Port 8080

The relay listens on port 8080. Add an ingress rule for TCP port 8080 to the subnet's security list (or to a network security group attached to the instance): Networking, Virtual cloud networks, your VCN, Security Lists, Add Ingress Rule with source 0.0.0.0/0 (or a tighter CIDR) and destination port 8080.

4. Test

curl "http://<PUBLIC_IP>:8080/api/mte-echo?msg=test"

Equivalent OCI CLI Command

The same instance can be created from the CLI:

oci container-instances container-instance create \
  --compartment-id <COMPARTMENT_OCID> \
  --availability-domain <AVAILABILITY_DOMAIN> \
  --display-name mte-relay \
  --shape CI.Standard.E4.Flex \
  --shape-config '{"ocpus": 1, "memoryInGBs": 4}' \
  --containers '[{ "imageUrl": "<region-key>.ocir.io/<tenancy-namespace>/mte-relay-server:4.7.0", "displayName": "mte-relay-server", "environmentVariables": { "DOMAIN_MAP": "{ \"*\": { \"upstream\": \"__YOUR_UPSTREAM_URL__\", \"client_id_secret\": \"__YOUR_CLIENT_ID_SECRET__\" } }" } }]' \
  --vnics '[{ "subnetId": "<SUBNET_OCID>", "isPublicIpAssigned": true }]'

Production notes

• Browsers require HTTPS. For production, place an OCI Load Balancer with a TLS certificate in front of the container instance, point your DNS record at it, and key DOMAIN_MAP on that hostname.
• A single container instance keeps pairing state in memory, which is fine on its own. To run multiple instances behind a load balancer, all of them must share state: set REDIS_URL on each instance and point it at OCI Cache (managed Redis) or a Redis server you operate.

---

Option B: Oracle Kubernetes Engine (OKE)

OKE runs standard Kubernetes, so the relay deploys with ordinary Kubernetes manifests. A Service of type LoadBalancer automatically provisions an OCI Load Balancer in front of the pods.

1. Connect kubectl to Your Cluster

Create a kubeconfig entry for your cluster (the exact command is also shown in the console under your cluster's Access Cluster panel):

oci ce cluster create-kubeconfig --cluster-id <CLUSTER_OCID> --file $HOME/.kube/config --region <REGION> --token-version 2.0.0

2. Create an Image Pull Secret

OKE needs credentials to pull from a private OCIR repository. Create a secret using the same OCIR login details from Step 2:

kubectl create secret docker-registry ocir-secret \
  --docker-server=<region-key>.ocir.io \
  --docker-username='<tenancy-namespace>/<username>' \
  --docker-password='<YOUR_AUTH_TOKEN>' \
  --docker-email='<username>'

3. Create the Manifest

Create a file named mte-relay-oke.yaml with the following content:

mte-relay-oke.yaml

# MTE Relay container deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mte-relay-deployment
spec:
  replicas: 2
  selector:
    matchLabels:
      app: mte-relay
  template:
    metadata:
      labels:
        app: mte-relay
    spec:
      imagePullSecrets:
        - name: ocir-secret
      containers:
        - name: mte-relay-server
          image: <region-key>.ocir.io/<tenancy-namespace>/mte-relay-server:4.7.0
          ports:
            - containerPort: 8080
          env:
            - name: DOMAIN_MAP
              value: '{ "relay.example.com": { "upstream": "__YOUR_UPSTREAM_URL__", "client_id_secret": "__YOUR_CLIENT_ID_SECRET__", "cors_origins": ["__YOUR_CORS_ORIGINS__"] } }'  # Update this value!
            - name: REDIS_URL
              value: "redis://my-redis-service:6379"

---

# MTE Relay Service; type LoadBalancer provisions an OCI Load Balancer
apiVersion: v1
kind: Service
metadata:
  name: mte-relay-service
  annotations:
    oci.oraclecloud.com/load-balancer-type: "lb"
    service.beta.kubernetes.io/oci-load-balancer-shape: "flexible"
    service.beta.kubernetes.io/oci-load-balancer-shape-flex-min: "10"
    service.beta.kubernetes.io/oci-load-balancer-shape-flex-max: "100"
spec:
  type: LoadBalancer
  selector:
    app: mte-relay
  ports:
    - protocol: TCP
      port: 80           # External port on the OCI Load Balancer
      targetPort: 8080

---

# Redis container deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-redis-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-redis
  template:
    metadata:
      labels:
        app: my-redis
    spec:
      containers:
        - name: redis
          image: redis:7.2
          ports:
            - containerPort: 6379

---

# Redis Service to expose the deployment
apiVersion: v1
kind: Service
metadata:
  name: my-redis-service
spec:
  type: ClusterIP
  selector:
    app: my-redis
  ports:
    - protocol: TCP
      port: 6379
      targetPort: 6379

The above configuration provides these resources:

• mte-relay-deployment (Deployment): Runs 2 replicas of the mte-relay-server container on port 8080, pulling the image from OCIR with the pull secret.
• mte-relay-service (Service - LoadBalancer): Provisions a flexible shape OCI Load Balancer that forwards external port 80 to container port 8080.
• my-redis-deployment (Deployment): Runs a single Redis instance on port 6379 so both relay replicas share pairing state.
• my-redis-service (Service - ClusterIP): Provides internal cluster access to the Redis pod over port 6379.

4. Deploy

kubectl apply -f mte-relay-oke.yaml

Watch the pods come up and wait for the load balancer to receive an external IP address:

kubectl get pods
kubectl get service mte-relay-service --watch

Once EXTERNAL-IP is populated, test the relay:

curl "http://<EXTERNAL_IP>/api/mte-echo?msg=test"

Remember to update the DOMAIN_MAP key to match the hostname clients will actually use (your DNS name pointing at the load balancer), or use a wildcard "*" key while testing by IP.

Kubernetes Commands

To check the logs of a running pod, use the command

kubectl logs <POD_NAME>

To scale up the number of replicas, use the command

kubectl scale deployment mte-relay-deployment --replicas=<NUMBER_OF_REPLICAS>

To delete the deployment and services (this also deletes the OCI Load Balancer), use the command

kubectl delete -f mte-relay-oke.yaml

TLS in production

For production traffic, terminate TLS in front of the pods. The common options on OKE are a TLS certificate on the OCI Load Balancer (listener annotations), or an ingress controller with cert manager. Whichever you choose, the DOMAIN_MAP key must match the public hostname.

Sources:
OKE: Pulling Images from Registry
OKE: Defining Load Balancers

---

Testing & Health Checks

• Monitor container logs for startup messages
• Use the default or custom echo routes to test container responsiveness:
  • Default: /api/mte-echo
  • Custom Message: /api/mte-echo?msg=test

Expected response:

{
  "message": "test",
  "timestamp": "<timestamp>"
}

---

Troubleshooting

1. Cannot push to OCIR (401 Unauthorized)
   • Verify the Docker login username is <tenancy-namespace>/<username> and the password is a current auth token, not your console password.
2. OKE pods stay in ImagePullBackOff
   • The pull secret is missing, misspelled, or not referenced in imagePullSecrets. Recreate ocir-secret and confirm the image URL region and namespace.
3. Requests rejected with 404 or no proxy destination found
   • The hostname used to reach the relay does not match a DOMAIN_MAP key. Use the exact DNS name or a wildcard "*" key.
4. Relay unreachable
   • Check the subnet security list or NSG for an ingress rule on the relay port, and verify the load balancer health checks are passing.
5. Redis connection issues
   • Ensure REDIS_URL is reachable from the relay pods or container instances.

---

Security

Container Hardening

MTE Relay Server is built and hardened using the following practices:

• Minimal base image: The runtime image uses Google's Distroless cc-debian12 base. It contains only the application and its runtime dependencies, with no shell, no package manager, and no general purpose OS utilities, which dramatically reduces the attack surface.
• Multi stage build: The application is compiled in a separate golang build stage. Build tooling and source never ship in the final image; only the compiled binary is copied forward.
• Unprivileged runtime: The container runs as a dedicated unprivileged user (nonroot). No root privileges are required at runtime.
• Minimal surface: Only port 8080 is exposed, and the image runs a single binary entrypoint.
• No persisted secrets: No sensitive data is stored in the container; all configuration is supplied at runtime via environment variables.

Vulnerability Scanning

Container images are scanned for known vulnerabilities with Docker Scout prior to release. Scan reports for the current image tag are available from Eclypses Support on request (see Support).

Because the image is pushed into your own OCIR repository, you can also generate native scan evidence by enabling repository scanning with the Oracle Vulnerability Scanning Service on the mte-relay-server repository. The pulled image can equally be scanned with any container scanner of your choice (e.g. Trivy or Grype) to produce evidence within your own environment.

---

Costs

OCI infrastructure costs (Container Instances, OKE worker nodes, load balancers, OCIR storage, and Redis or OCI Cache) are billed to your Oracle Cloud account and are customer managed.

---

Maintenance

Release Cadence

Updated container images are published on an as needed basis, when new features, dependency updates, or fixes warrant a release. Security patches are issued out of band as needed and are not tied to a fixed calendar cadence. Each release is versioned (see the image tag, e.g. 4.7.0) and distributed through Eclypses' Amazon ECR repository.

Patch SLA

Eclypses' commitment for security patches:

• Critical vulnerabilities are addressed in a patched image within 30 days of confirmed disclosure.
• Lower severity issues are addressed in a subsequent release.

To receive an updated image, pull the latest tag from the Eclypses ECR repository, push it to your OCIR repository, and redeploy the container instance or update the OKE deployment manifest to reference the new tag.

Fault Recovery

• Relaunch the Relay container; clients will automatically pair again.

---

Support

MTE Relay Server is a commercially supported product from Eclypses. Support and security patch SLAs (including the 30 day critical patch commitment described under Maintenance) are provided to licensed/subscribed customers. For escalations, scan reports, or hardening documentation, contact Eclypses Support:
customer_support@eclypses.com
Monday through Friday, 8:00 AM to 5:00 PM MST (excluding holidays)