Using Docker

How to run MarketGrid using Docker.

This article will guide you through running MarketGrid using Docker. This is ideal for local testing, or for a simple deployment using Docker Compose.

Prerequisites (Docker installation)

A Windows or Mac OS X machine with Docker Desktop (download here), or a Linux machine with Docker Engine installed (see Ubuntu install instructions here).

Obtaining the MarketGrid image

You will need to log in to the MarketGrid image registry the first time you run Docker after installing. To login to the registry, use your GitLab username and a personal access token.

Interactive login:

docker login registry.cartax.io

Non-interactive login:

docker login -u ${GITLAB_USER} -p ${GITLAB_TOKEN} registry.cartax.io

Once authenticated, you will be able to pull images using the docker pull command. For example:

docker pull registry.cartax.io/platform/meta/marketgrid:v15.50.0

Configuration

To configure and run the container, there are two options:

  1. Using docker run
  2. Using Docker Compose

Using docker run

This is the most basic way to start a MarketGrid container.

docker run \
	--detach \
	--shm-size=8g \
	--publish 10443:10443 \
	--hostname docker.marketgrid.systems \
	registry.cartax.io/platform/meta/marketgrid:v15.50.0 \
	tail -f /dev/null

This command starts the container in the background. It will keep running until it is stopped using docker stop.

Two options are worth highlighting:

  • --shm-size: This is required for any MarketGrid container. MarketGrid uses shared memory to share data between each the services that run within the container.
  • --publish: This publishes the port on which the MarketGrid UI server listens so that the UI is accessible from the host system.

For complete information on docker run options, refer to the Docker run reference.

The running container can be found using docker ps:

> docker ps
CONTAINER ID   IMAGE                                                  COMMAND                  CREATED         STATUS         PORTS                                           NAMES
12db385c6902   registry.cartax.io/platform/meta/marketgrid:v15.50.0   "docker-entrypoint.s…"   4 seconds ago   Up 3 seconds   0.0.0.0:10443->10443/tcp, :::10443->10443/tcp   sharp_gates

Using Docker Compose

Docker Compose can be helpful if you want to use more complex configurations, especially those involving networking and volume setups, or multiple containers.

An example docker-compose.yml file for a single MarketGrid container is provided below.

version: '3.9'
services:
  mg:
    image: registry.cartax.io/platform/meta/marketgrid
    command: mg start equities_test_data_s_yaml
    container_name: marketgrid
    hostname: ${CONTAINER_HOSTNAME}
    shm_size: 8gb
    network_mode: "host"
    volumes:
    - type: bind
      source: ./scenarios/demo/equities_test_data_s.yaml
      target: /opt/MarketGrid/mg/src/packages/demo/scenarios/equities_test_data_s.yaml
    - type: bind
      source: ./datasets/
      target: /opt/MarketGrid/datasets/
    - type: bind
      source: ./logs
      target: /opt/MarketGrid/logs
    - type: bind
      source: ./kdb_licence/
      target: /opt/q/licences/x.marketgrid.systems
    - type: bind
      source: ./data/
      target: /opt/MarketGrid/data/

We will only consider relevant sections of this docker-compose.yml file. For a full reference, refer to the Docker Compose manual.

In the example above, we have defined a single service that will use the image we pulled from the container registry earlier.

The example includes host networking, so all ports are shared between the container and host. A ports section can be included, which defines port mappings between host and container networks. You should re-direct any necessary ports that are relevant to your development work. The ports 10080, 10443, and 9229 are used to view the UI via both HTTP and HTTPS, and to debug the UI server respectively.

The volumes persist data in the specified target directories past the lifetime of the container, and can be shared with other containers. This is useful for tweaking the static data files, for example.

Troubleshooting

Inspecting the state of a running container

To view the state of each service within a container, use docker exec to run the mg status command within the container:

docker exec -it ${container_id} mg status

Viewing the logs

If any of the MarketGrid services are not running, check for error messages in the container's log:

docker logs ${container_id}

Permissions issues

If there are permissions issues with any of the mounted volumes in the running container, try confirming that the Group ID (GID) matches on the host and container and that the volume has group read+write permissions.

The mg user inside the container has a UID and GID of 10000. If the user on your host has a different GID, use the user option in docker-compose or docker run command line options to match. For example, adding user: “mg:1001” to the compose yaml where 1001 is the GID of the host user, or if running the container using the docker run command, include --user mg:$(id -g).

← Introduction
Using Kubernetes →