Reliable, high-performance Docker images for running Interactive Brokers Gateway and TWS with full automation and robust process management.

Images: danklabs/ib-gateway • danklabs/ib-tws

VNC_PWD must be set, or VNC will not start. IB_USER and IB_PASSWORD must be provided.

# 1. Get the project
git clone https://github.com/djkelleher/ib-docker.git
cd ib-docker

# 2. Configure credentials
cp .env.example .env
# Edit .env with your IB username and password

# 3. Start container
docker compose up -d

# 4. Connect your trading app to localhost:4002 (paper) or localhost:4001 (live)

Enable the web interface to monitor all processes:

environment:
  SUPERVISORD_UI_PORT: 9001
  SUPERVISORD_UI_USER: admin    # Optional
  SUPERVISORD_UI_PASS: secret   # Optional

Access: http://localhost:9001

View process status & logs:

docker compose exec ib-gateway supervisorctl status
docker compose exec ib-gateway supervisorctl tail -f ibc

• 🔄 Full Automation - IBC handles login and session management
• 🖥️ Headless Operation - Xvfb virtual display + x11vnc for remote GUI access
• 📊 Process Management - Supervisord with auto-recovery and web monitoring
• 🌐 Flexible Networking - Host networking or bridge mode configurations
• 📈 Production Ready - Health checks, logging, and high-availability patterns
• 🐳 Multi-stage Build - All install logic embedded in build/Dockerfile (legacy install.sh removed)

Benefits:

• Auto-recovery of failed processes
• Web interface at http://localhost:9001 (optional)
• Independent logging for each service
• Proper startup dependencies

# Build gateway (stable)
docker build -t danklabs/ib-gateway:stable \
  --build-arg PROGRAM=ibgateway --build-arg RELEASE=stable build/

# Build TWS (stable)
docker build -t danklabs/ib-tws:stable \
  --build-arg PROGRAM=tws --build-arg RELEASE=stable build/

Optional build args:

services:
  ib-gateway:
    image: danklabs/ib-gateway:stable
    network_mode: host
    environment:
      TRADING_MODE: paper

Access: localhost:4001 (paper: localhost:4002)

services:
  ib-gateway:
    image: danklabs/ib-gateway:stable
    ports:
      - "4001:4001"
      - "4002:4002"
      - "5900:5900"
    environment:
      TRADING_MODE: paper

1. Credentials: Use .env files, never commit passwords
2. VNC: Set strong VNC_PWD if enabling VNC server
3. Monitoring: Enable supervisord web interface only on trusted networks
4. Updates: Regularly update container images and dependencies

Same as Ports table above. Map or expose as required.

# Example custom Java options
JAVA_OPTS="-Xmx2g -Xms1g -XX:+UseG1GC"

The container supports two main networking patterns: host and bridge (shown above). Choose based on isolation vs simplicity.

The historical build/install.sh helper script has been removed. All install logic is now implemented directly inside the multi-stage build/Dockerfile (builder stage). This reduces duplication and ensures reproducible builds.

MIT

Issues and PRs welcome. Please open an issue for feature discussions first.