ThetaData Terminal Docker

Production-ready Docker implementation for ThetaData Terminal with multi-instance support, cross-platform compatibility, and enterprise-grade configuration.

Features

• 🚀 Cross-platform support (Linux, macOS, Windows, ARM64)
• 🔧 Multiple deployment options (Docker Run, Docker Compose)
• 🏗️ Multi-instance support for running production and test environments
• 📊 WebSocket and REST API endpoints
• 🔒 Secure credential management
• ⚡ Optimized for low latency with configurable memory settings

Prerequisites

• Docker Engine 20.10+
• Docker Compose 2.0+ (optional)
• ThetaData account (Sign up here)
• 8GB+ RAM (16GB recommended)

Quick Start

Option 1: Using Docker Run

# Pull and run with environment variables
docker run -d \
  --name theta-terminal \
  -p 25510:25510 \
  -p 25520:25520 \
  -p 11000:11000 \
  -p 10000:10000 \
  -e THETA_USERNAME="your-email@example.com" \
  -e THETA_PASSWORD="your-password" \
  -e JAVA_OPTS="-Xms4G -Xmx8G" \
  ghcr.io/userfrm/thetadata/terminal:latest

# Check logs
docker logs -f theta-terminal

# Test connection
curl http://localhost:25510/v2/system/mdds/status

Option 2: Using Docker Compose (Recommended)

1. Clone the repository:

git clone https://github.com/userFRM/thetadata-terminal-docker.git
cd thetadata-terminal-docker

2. Configure credentials:

cp .env.example .env
# Edit .env with your credentials
nano .env

3. Start the terminal:

docker-compose up -d

Configuration

Ports

Port	Service	Description
25510	REST API	HTTP endpoints for data queries
25520	WebSocket	Real-time streaming data
11000	MDDS Socket	Query-based data access
10000	FPSS Socket	Streaming data access

Memory Settings

Configure based on your system and usage:

# Standard (Recommended)
JAVA_OPTS="-Xms4G -Xmx8G"

# High Performance
JAVA_OPTS="-Xms8G -Xmx16G"

# Low Memory
JAVA_OPTS="-Xms2G -Xmx4G"

Environment Variables

Variable	Description	Default
THETA_USERNAME	Your ThetaData email	Required
THETA_PASSWORD	Your ThetaData password	Required
JAVA_OPTS	Java memory settings	-Xms4G -Xmx8G
TZ	Timezone	UTC

Advanced Usage

Running Multiple Instances

Run production and test terminals simultaneously:

# Production (default ports)
docker run -d \
  --name theta-prod \
  -p 25510:25510 -p 25520:25520 \
  -e THETA_USERNAME="your-email@example.com" \
  -e THETA_PASSWORD="your-password" \
  ghcr.io/userfrm/thetadata/terminal:latest

# Test environment (different ports)
docker run -d \
  --name theta-test \
  -p 25511:25511 -p 25521:25521 \
  -e THETA_USERNAME="your-email@example.com" \
  -e THETA_PASSWORD="your-password" \
  -v $(pwd)/config:/opt/theta/config \
  ghcr.io/userfrm/thetadata/terminal:latest \
  --config=/opt/theta/config/config_1.properties

Using Credentials File

For better security, use a credentials file instead of environment variables:

# Create credentials file
cat > creds.txt << EOF
your-email@example.com
your-password
EOF
chmod 600 creds.txt

# Run with credentials file
docker run -d \
  --name theta-terminal \
  -p 25510:25510 -p 25520:25520 \
  -v $(pwd)/creds.txt:/creds.txt:ro \
  ghcr.io/userfrm/thetadata/terminal:latest \
  --creds-file=/creds.txt

Persistent Storage

Mount volumes for logs and configuration:

docker run -d \
  --name theta-terminal \
  -p 25510:25510 -p 25520:25520 \
  -e THETA_USERNAME="your-email@example.com" \
  -e THETA_PASSWORD="your-password" \
  -v $(pwd)/config:/opt/theta/config \
  -v $(pwd)/logs:/opt/theta/logs \
  -v $(pwd)/data:/root/.theta \
  ghcr.io/userfrm/thetadata/terminal:latest

Performance Tuning

Network Latency

Docker adds minimal network overhead - typically only 5 microseconds (μs) to network latency within a data center. For most financial applications, this is negligible compared to internet latency to ThetaData servers.

Host Network Mode (Linux Only)

For absolute lowest latency, you can use host networking mode which removes NAT overhead by allowing containers to share the host's network stack:

# Host networking - bypasses Docker network layer
docker run -d \
  --name theta-terminal \
  --network host \
  -e THETA_USERNAME="your-email@example.com" \
  -e THETA_PASSWORD="your-password" \
  ghcr.io/userfrm/thetadata/terminal:latest

Note: With host networking, you don't need to map ports as the container uses the host's network directly.

Advanced Performance Options

For maximum performance (use with caution - security implications):

# In docker-compose.yml
services:
  theta-terminal:
    # ... other settings ...

    # Performance optimizations (USE WITH CAUTION)
    # privileged: true              # Grants all capabilities
    # network_mode: host            # Use host network stack
    # security_opt:
    #   - seccomp:unconfined       # Disable seccomp filters

Warning: The --privileged flag gives all capabilities to the container and allows nearly the same access to the host as processes running outside containers. Only use these options if you fully understand the security implications.

When to Consider These Options

1. Default configuration is recommended for most users
2. Host networking may help if you need sub-millisecond latency
3. Privileged mode should only be used in trusted environments where security is not a concern

The dominant latency factor will always be your internet connection to ThetaData servers (typically 50-100ms), not Docker overhead.

API Examples

REST API

# Get stock quote
curl "http://localhost:25510/v2/snapshot/stock/quote?root=AAPL"

# Get historical data
curl "http://localhost:25510/v2/hist/stock/trade?root=AAPL&start_date=20240101&end_date=20240101"

# Check system status
curl "http://localhost:25510/v2/system/mdds/status"
curl "http://localhost:25510/v2/system/fpss/status"

WebSocket Streaming

import asyncio
import websockets
import json

async def stream_trades():
    uri = "ws://localhost:25520/v1/events"

    async with websockets.connect(uri) as websocket:
        # Subscribe to trades
        subscribe = {
            "msg_type": "STREAM_BULK",
            "sec_type": "OPTION",
            "req_type": "TRADE",
            "add": True,
            "id": 0
        }

        await websocket.send(json.dumps(subscribe))

        while True:
            message = await websocket.recv()
            print(json.loads(message))

asyncio.run(stream_trades())

Building from Source

If you want to build the image yourself:

# Clone repository
git clone https://github.com/userFRM/thetadata-terminal-docker.git
cd thetadata-terminal-docker

# Build image
docker build -t thetadata/terminal .

# Run your built image
docker run -d \
  --name theta-terminal \
  -p 25510:25510 -p 25520:25520 \
  -e THETA_USERNAME="your-email@example.com" \
  -e THETA_PASSWORD="your-password" \
  thetadata/terminal

Troubleshooting

Container won't start

# Check logs
docker logs theta-terminal

# Verify credentials
docker run -it --rm ghcr.io/userfrm/thetadata/terminal:latest --help

Connection issues

# Test from inside container
docker exec theta-terminal curl http://localhost:25510/v2/system/mdds/status

# Check port availability
netstat -tulpn | grep -E "25510|25520"

Performance issues

# Monitor resource usage
docker stats theta-terminal

# Adjust memory settings
docker run -d \
  --name theta-terminal \
  -e JAVA_OPTS="-Xms8G -Xmx16G" \
  ghcr.io/userfrm/thetadata/terminal:latest

Health Monitoring

The container includes automatic health checks every 240 seconds:

# Check health status
docker inspect theta-terminal --format='{{.State.Health.Status}}'

# View health check history
docker inspect theta-terminal --format='{{range .State.Health.Log}}{{.Output}}{{end}}'

License

This Docker implementation is MIT licensed. ThetaData Terminal itself requires a valid license from ThetaData.

Support

• Docker Issues: Create an issue
• ThetaData Support: Discord
• Documentation: ThetaData Docs

---

Made with ❤️ by the ThetaData Community