rsmb7z / ibkr-docker

Run IBKR Gateway/TWS in a Docker container

Interactive Brokers in Docker

• Interactive Brokers in Docker
  • Features
  • Getting Started
    • Using docker run
    • Using docker compose (recommended)
    • Environment Variables
  • Docker Images
  • FAQ
    • How do I save TWS settings locally?
    • Cannot connect to API when using TWS
    • Error: library initialization failed - unable to allocate file descriptor table - out of memory/root/ibc/scripts/ibcstart.sh
    • Which tag to use, latest or stable?
    • What is the difference between IB Gateway and Trader Workstation (TWS)?
    • Do I need to download TWS separately?
    • What ports does TWS/IB Gateway use internally?
    • How do I configure the default login to paper/live trading?
  • Repository Architecture

Trader Workstation

IB Gateway

Features

• Fully containerized TWS/IB Gateway, no external dependencies
• TWS API access automatically configured and forwarded
• Viewable in a browser (via noVNC)
• Auto-restart, auto-login TWS/IB Gateway automatically via IBC Alpha

Getting Started

Using docker run

docker run -d \
  -p "127.0.0.1:6080:6080" \
  -p "127.0.0.1:8888:8888" \
  --ulimit nofile=10000 \
  -e USERNAME=your_username \
  -e PASSWORD=your_password \
  ghcr.io/extrange/ibkr:latest

Using docker compose (recommended)

Create a .env file:

USERNAME=<your IBKR username>
# wrap password in single quotes if $, /, or \ are present
PASSWORD='<your IBKR password>'

compose.yml:

---
services:
  ibkr:
    image: ghcr.io/extrange/ibkr # latest, stable, 10.21, 10.21.1p etc
    ports:
      - "127.0.0.1:6080:6080" # noVNC browser access
      - "127.0.0.1:8888:8888" # API access
    ulimits:
      nofile: 10000 # See FAQ
    environment:
      USERNAME: ${USERNAME}
      PASSWORD: ${PASSWORD}
      # TWOFA_TIMEOUT_ACTION: restart
      # GATEWAY_OR_TWS: tws
      #
      # Variables prefixed with IBC_ override IBCAlpha`s config.ini:
      # IBC_TradingMode: live
      # IBC_ReadOnlyApi: yes
      # ...
      # See below for more details

Important: Boolean-like values (e.g. yes/no) must be wrapped in single quotes to prevent them from being interpreted as True/False by th YAML parser.

View at localhost:6080.

TWS API is accessible at port 8888.

Environment Variables

Variable	Description	Default
USERNAME	Username	edemo
PASSWORD	Password	demouser
GATEWAY_OR_TWS	What to start, either tws or gateway	tws
TWOFA_TIMEOUT_ACTION	2FA timeout action. Either restart or exit.	restart
TWS_SETTINGS_PATH	(optional) Path to store TWS settings (see FAQ)

Variables prefixed with IBC_ will override settings in IBCAlpha's config.ini, e.g.:

• IBC_TradingMode (default: live)
• IBC_ExistingSessionDetectedAction (default: manual)
• IBC_ReadOnlyApi (default: keep existing)
• etc.

See possible values here.

Docker Images

See available tags and versions here.

FAQ

How do I save TWS settings locally?

If you want to save TWS settings locally (e.g. to persist settings across container runs), set TWS_SETTINGS_PATH to say, /settings. Then, add a bind mount on your local filesystem, such as in the following compose.yml:

#...
  environment:
    TWS_SETTINGS_PATH: /settings
    #...
  volumes:
    - ./settings:/settings:rw

Now, TWS will load settings from your local filesystem for each container run.

Cannot connect to API when using TWS

You will need to manually enable Enable ActiveX and Socket Clients (see this issue).

Error: library initialization failed - unable to allocate file descriptor table - out of memory/root/ibc/scripts/ibcstart.sh

Ensure that you have the appropriate ulimit nofile set: either --ulimit nofile=10000 (docker run) or ulimits: nofile: 10000 (docker compose).

Which tag to use, latest or stable?

stable is generally preferred as there are less bugs.

What is the difference between IB Gateway and Trader Workstation (TWS)?

TWS is a fully featured trading platform with many features.

IB Gateway has a minimal GUI and is used for API access to the trading platform, for example with automated trading. It also uses less resources.

See here for more differences.

Do I need to download TWS separately?

Both the IB Gateway and TWS installation scripts include both IB Gateway and TWS, so downloading either is fine.

What ports does TWS/IB Gateway use internally?

TWS uses 7496 (live) and 7497 (paper), while IB gateway uses 4001 (live) and 4002 (paper).

There is no need to change the port for this image, as it automatically forwards the correct port (based on trading mode and TWS/IB Gateway) to 8888.

How do I configure the default login to paper/live trading?

Set the environment variable IBC_TradingMode to paper or live.

Repository Architecture

• New versions of IB Gateway are checked for daily, and fetched if available, as a release (detect-releases.yml).
• A PR with the updated Dockerfile (obtained by running build.sh <latest/stable> <version>) is automatically created
• I test the updated configuration (both IB Gateway/TWS)
• I then manually merge the PR, and tag the resulting commit with git tag docker-<version>-<latest/stable>
• Pushing the tag triggers a docker build action (publish.yml, based on the docker- prefix), which reads the version and release channel (latest/stable) from the tag, and then fetches the repo at the tag's commit, builds from the appropriate folder (latest/stable), tags and pushes the image to ghcr.io/extrange/ibkr.