Topics

#algorithmic-trading #api-gateway #aws-ecs #cloud-native #container #containerization #docker #fintech #headless #ib-async #ib-gateway #ibc #ibkr #interactive-brokers-api #kubernetes #production-ready #quant #vnc

Language breakdown

Shell 79.6%

Dockerfile 16.2%

Python 4.2%

▸ Files click to expand

README

Docker IB Gateway

What is it?

A project that containerizes IB Gateway (Interactive Brokers Gateway) with IBC (Interactive Brokers Controller) to enable automated trading without a graphical interface.

This project is based on extrange/ibkr-docker but with a different approach by Hartza Capital.

Build Status

Main Features

Fully containerized: IB Gateway + IBC in a complete Docker container
Automated startup: Gateway startup is handled by IBC (Interactive Brokers Controller)
Auto-restart: Automatic restart on disconnection (like IB's daily disconnect)
VNC support: GUI access via VNC for debugging
Multi-channel: Support for stable and latest versions — long-lived releases (12 weeks expiration), weekly builds on Sundays
Python scripts: Debugging tools in debug to test API connections
Weekly releases: Automated releases on stable and latest channels every Sunday
Cloud-ready: Works perfectly on AWS ECS/Kubernetes. Hartza Capital uses a customized version on AWS ECS in production
Extensible: You can add your own custom scripts within the container (though this is generally considered a bad practice, it's the simplest approach given the gateway's security criticality and IBKR gateway's rigidity)

Project Structure

build.sh: Automated build script that handles different channels and fetches versions dynamically
docker-compose.yaml: Configuration to start the container easily with volume mounts for local development
gateway/Dockerfile: Multi-stage build with IB Gateway, IBC, and process supervisor
gateway/config.ini: IBC configuration for automation
gateway/unstoppable.conf: Process supervisor configuration for service management
gateway/scripts/: Startup and VNC initialization scripts
.github/workflows/: Automated CI/CD (buildstable.yml, buildlatest.yml) to build and publish images to Quay.io

Quick Start

Using Docker Compose (Recommended)

Clone the repository:

git clone https://github.com/hartza-capital/docker-ib-gateway.git
cd docker-ib-gateway

Configure your credentials in gateway/config.ini:

IbLoginId=your_username
IbPassword=your_password
TradingMode=paper  # or 'live' for production

Start the container:

docker-compose up -d

Access VNC GUI (optional) at localhost:5900 with password test
Connect your trading application to API on ports 4001 (live) or 4002 (paper)

Using Pre-built Images

Pull and run directly from Quay.io:

# Stable channel (recommended for production)
docker run -d \
  -p 5900:5900 -p 4001:4001 -p 4002:4002 \
  -e VNCSERVERPASSWORD=test \
  quay.io/hartza-capital/ib-gateway:stable
Latest channel (most recent features)
docker run -d \
  -p 5900:5900 -p 4001:4001 -p 4002:4002 \
  -e VNCSERVERPASSWORD=test \
  quay.io/hartza-capital/ib-gateway:latest

Building from Source

Build your own image:

# Build stable channel
./build.sh stable
Build and push to your registry
./build.sh stable --push

Configuration

IBC Configuration (`gateway/config.ini`)

Key settings for automation:

# Authentication
IbLoginId=your_username
IbPassword=your_password
Trading mode
TradingMode=live  # or 'paper'
Auto-restart (daily restart at specified time)
AutoRestartTime=02:00 AM
Session handling
ExistingSessionDetectedAction=primaryoverride

Environment Variables

VNCSERVERPASSWORD: Password for VNC access (default: no password)

Port Mapping

4001: IB Gateway Live Trading API
4002: IB Gateway Paper Trading API
5900: VNC server for GUI access
8080: Health check endpoint

Client SDKs

Once the gateway is running, connect your trading application using one of the official or community SDKs:

IBKR API (official) — Official documentation and native client libraries (Java, C++, Python, C#)
ibasync — Community asyncio Python client (continuation of ibinsync), used by the debug scripts in this repo

Debug Tools

Python scripts in gateway/debug/ help test API connectivity:

# Install dependencies
pip install -r gateway/debug/requirements.txt
Test contract details
python gateway/debug/contract_details.py
Check positions
python gateway/debug/positions.py

Production Deployment

The container image is compatible with AWS ECS and Kubernetes deployments. Use standard container orchestration practices:

Memory: Recommend minimum 2GB, ideally 2-4GB depending on trading volume
CPU: Recommend minimum 1 core (1000m in Kubernetes)
Volumes: Mount /home/trader/.ibrokerscache for persistent session data if needed
Environment: Set VNCSERVERPASSWORD for secure access
Ports: Expose 4001 (live), 4002 (paper), 8080 (health), optionally 5900 (VNC)

Release Channels

| Channel | Update Frequency | Lifespan | Use Case | | --------- | ---------------------------- | -------- | ----------------------- | | stable | Weekly (Sundays at 5:00 UTC) | 12 weeks | Production environments | | latest | Weekly (Sundays at 5:00 UTC) | 12 weeks | Development/testing |

Architecture Overview

External Dependencies

The container depends on three external components:

IB Gateway (Interactive Brokers)

- Official trading gateway from Interactive Brokers - Downloaded from: https://download2.interactivebrokers.com/installers/ibgateway/{channel}-standalone/ - Provides Live and Paper trading APIs

IBC (Interactive Brokers Controller)

- Open-source project: IbcAlpha/IBC on GitHub - Automates gateway startup, login, and configuration - Downloaded from GitHub releases during build

Unstoppable (Hartza Capital)

- Process supervisor: quay.io/hartza-capital/unstoppable (public image) - Manages process lifecycle with auto-restart - Provides health checks on port 8080

Build Process

The container uses a multi-stage build:

Build stage: Downloads IB Gateway installer and IBC from GitHub releases
Runtime stage: Python 3.14 slim base with X11/VNC support and rootless user (trader)
Entry point: unstoppable service manages IBC startup, X11/VNC server, and health monitoring

Security Considerations

Credentials: Never hardcode credentials in config files. Use environment variables or secrets management
Rootless: Runs as unprivileged trader user (UID 10001) with no root access
Network: Restrict API access to trusted IP addresses only
VNC: Use strong passwords for VNC access and disable if not needed
Updates: Regularly update to latest stable releases for security patches
Process supervisor: Uses public quay.io/hartza-capital/unstoppable image (source code is private at Hartza Capital)

Troubleshooting

Common Issues

Gateway won't start:

Check credentials in config.ini
Verify trading mode matches account type
Check IBC logs: docker exec <container_id> tail -f /home/trader/ibc/logs/ibc.log
Verify IBC version compatibility (see CLAUDE.md for version details)
Check overall logs: docker logs <container_id>

API connection refused:

Ensure ports 4001/4002 are exposed and accessible
Check if gateway is fully initialized (can take 1-2 minutes)
Verify API is enabled in gateway settings

VNC connection fails:

Check VNCSERVERPASSWORD environment variable
Ensure port 5900 is exposed
Wait for X11 server initialization

Logs and Debugging

# View container logs
docker logs ib-gateway-container
Access container shell
docker exec -it ib-gateway-container bash
Check IBC logs
docker exec ib-gateway-container tail -f /home/trader/ibc/logs/ibc.log