Skip to main content

SocketX on AWS

Introduction​

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

Below is an example architecture where a client application communicates with a SocketX Server, which then proxies decoded WebSocket traffic to backend services:

Socket X Diagram

Prerequisites​

Technical Requirements​

  • A web or mobile application project that communicates with a backend service over WebSockets.

Skills and Knowledge​

  • Familiarity with ECS and/or EKS.
  • Experience with the AWS CLI.

Deployment Options​

SocketX Server is provided as a Docker image and can be deployed on AWS ECS, AWS EKS, or manually using another container runtime.

1. Elastic Container Service (ECS)​

Requirements​

  • Git
  • AWS CLI
  • AWS permissions to launch resources

Deployment Steps​

  1. Clone the GitHub repository:
    AWS CloudFormation Templates
  2. Modify the parameters.json file with your configuration.
  3. From the template directory, run the deploy.sh create command to deploy, or the delete command to remove resources.

Configuration​

Modify the parameters.json file to configure your deployment:

Required parameters:

  • VpcId - Your AWS VPC ID.
  • Subnets - Comma-separated list of subnet IDs. Requires at least two.
  • DomainMap - A JSON object mapping domain names to their corresponding proxy targets. Wildcards are supported!

Optional parameters include:

  • LogLevel - Logging level. Values are debug, info, warn, error, fatal,panic, off. Default is info.
paramters.json
[
  {
    "ParameterKey": "VpcId",
    "ParameterValue": ""
  },
  {
    "ParameterKey": "SubnetIds",
    "ParameterValue": ""
  },
  {
    "ParameterKey": "DomainMap",
    "ParameterValue": "{\"*\":\"ws://example.com\"}"
  },
  {
    "ParameterKey": "LogLevel",
    "ParameterValue": "warning"
  }
]

2. Docker Image​

You can also run the image using Docker, Podman, K3s, or Docker Swarm.

Commands​

aws ecr get-login-password \
--region us-east-1 \
| docker login --username AWS \
--password-stdin 709825985650.dkr.ecr.us-east-1.amazonaws.com

docker pull 709825985650.dkr.ecr.us-east-1.amazonaws.com/eclypses/socketx-server:1.0.0

Refer to the Server Configuration section for required environment variables.

Server Configuration​

SocketX Server is configured using environment variables.

Required Variables​

  • DOMAIN_MAP - JSON string mapping domains. Wildcards are supported.

Optional Variables​

  • LISTEN_HOST - Default: 0.0.0.0.
  • LISTEN_PORT - Default: 8080.
  • LOG_LEVEL - One of debug, info, warn, error, panic, off. Default: info.
  • WS_READ_BUFFER_SIZE - Websocket read buffer size in bytes. Default: 1024.
  • WS_WRITE_BUFFER_SIZE - Websocket write buffer size in bytes. Default: 1024.

Minimal Example​

DOMAIN_MAP={"*":"ws://example.com"}

Full Example​

DOMAIN_MAP={"*":"ws://example.com"}
LISTEN_HOST=0.0.0.0
LISTEN_PORT=8080
LOG_LEVEL=info
WS_READ_BUFFER_SIZE=2048
WS_WRITE_BUFFER_SIZE=2048

Client-Side Setup​

Eclypses provides client-side SDKs to integrate with SocketX Server:

Testing & Health Checks​

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

Expected response:

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

Troubleshooting​

  1. Invalid Configuration
    • Check logs for missing/invalid environment variables.
  2. SocketX unreachable
    • Verify Security Groups and load balancer settings.
  3. Redis connection issues
    • Ensure Redis is in the same VPC and credentials are correct.

Enable debug logs by setting the environment variable LOG_LEVEL=debug.

Security​

  • No sensitive data is stored in the container.
  • No root privileges required.

Costs​

The service uses a usage-based cost per instance per hour.
Associated AWS services include:

AWS ServicePurpose
ECSContainer orchestration
CloudWatchLogging and monitoring
VPCNetworking isolation
Elastic Load BalancerScaling across Relay containers

Maintenance​

Routine Updates​

  • Updated container images are distributed through the AWS Marketplace.

Fault Recovery​

  • Relaunch the Relay container task; clients will automatically re-pair.

Service Limits​

Supported Regions​

SocketX Server is supported in most AWS regions, except:

  • GovCloud
  • Middle East (Bahrain, UAE)
  • China

Support​

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