Quick Start

Quick Start

This guide takes you from nothing to a running Elastic MDS system streaming simulated market data, on a single machine, in about 20 minutes. You will start the system, confirm it is healthy, and watch a stream of simulated data arrive at a subscribing client.

Elastic MDS is a set of cooperating services. This guide runs them together on one machine using Docker Compose, because that is the quickest way to get going - but the services are not tied to Compose, or to any one machine (more on that below).

What this is - and what it isn't. This Quick Start runs Elastic MDS on a single host and feeds it with a simulator that replays recorded market data. It is the fastest way to see the system working and to explore it hands-on - an evaluation and learning setup. It is not how you would run Elastic MDS for real: a production system spreads its work across machines and scales the parts that need it. There is no rush to get there - when you are ready, Deployment: Basics walks you through the options.

Audience: anyone evaluating Elastic MDS. No prior MetaFluent knowledge assumed.

---

Before you begin

You need four things. The first two are generic; follow the linked instructions if you do not already have them.

#	Requirement	How to get it
1	A Linux host with a shell.	Any modern Linux distribution. (macOS or Windows with Docker Desktop also work; the commands are the same, but this guide assumes Linux.)
2	Docker Engine + the Docker Compose plugin.	Follow Docker's official install guide: https://docs.docker.com/engine/install/. Then verify: docker --version and docker compose version should both print a version.
3	A GitHub account with access to MetaFluent images.	The images are private. Sign up at https://github.com/join using your corporate email, then email support@metafluent.com to request access. Once you are granted access to the MetaFluent projects, access to the corresponding images follows automatically.
4	A GitHub Personal Access Token (PAT) with the read:packages scope.	Create a classic PAT: https://github.com/settings/tokens. Tick read:packages. Copy the token somewhere safe - you cannot view it again.

---

Step 1 - Log in to the image registry

Elastic MDS images are published to the GitHub Container Registry, ghcr.io. Authenticate Docker to it once, using the PAT from requirement 4:

export CR_PAT=<your-personal-access-token>
echo "$CR_PAT" | docker login ghcr.io -u <your-github-username> --password-stdin

You should see Login Succeeded.

Stuck here? If you see denied or unauthorized, the login worked but your account cannot see the images yet - that is an access grant, not a Docker problem. Confirm you completed requirement 3 (and that the grant has been applied), then try again. This is the single most common place newcomers get stuck, so it is worth getting right before moving on.

---

Step 2 - Set up the gateway hostname

Everything you do to monitor an Elastic MDS system - checking health, reading statistics, controlling it - goes through its API gateway. Across the documentation, and in real deployments, the gateway is addressed by a stable convention name: mf-api-gateway. Map that name to your own system now, before you start anything, so the same commands work here and everywhere else:

echo "127.0.0.1 mf-api-gateway" | sudo tee -a /etc/hosts

This /etc/hosts entry is all you need for this single-machine demo. For a permanent, network-wide mapping - a real DNS entry rather than a hosts file - see Setting up a DNS entry for your API Gateway.

Why this matters. Using the convention name (rather than localhost) means every gateway command in this guide, in the rest of the docs, and the built-in tools such as sim-ctl - which is hardwired to mf-api-gateway:9090 - all work unchanged, here and when you later move to a multi-container or production deployment. It is a small step that keeps your commands portable.

If you skip it. You can substitute localhost for mf-api-gateway in the commands below and the basic checks still work - but tools hardwired to the convention name will not, until you add the mapping. Do it now and you will not have to think about it again.

---

Step 3 - Get the system

Clone the deployment recipes and enter the consolidated one:

git clone git@github.com:MetaFluent/docker-compositions.git
cd docker-compositions/consolidated

The consolidated recipe is a docker-compose.yml that runs two containers:

• mf-mds-consolidated - the entire Elastic MDS system in one container: the API gateway, the session / pub-sub / SQL query servers, the push and refresh distribution servers, and a market-data projector. This one container is your Elastic MDS.
• mf-eta-simulator - a separate simulator that replays recorded market data (equities, indices) as a stream, so you have something to look at without connecting a real data source.

Would rather not use Compose? Compose is just a convenience for running the two pieces together. You can instead run each from its own deployment project - clone deploy-mf-mds-consolidated and deploy-mf-eta-simulator and start each with its provided scripts/start (and stop it with scripts/stop). Either route gives you the same running system, and in a real deployment the pieces need not share a host at all. This guide uses Compose purely for brevity.

---

Step 4 - Start the system

Compose needs to know which host user account owns the files the containers write. Set that, then bring everything up:

export METAFLUENT_HOST_UID=$(id -u)
docker compose up -d

The first run downloads the images from ghcr.io, so it takes a few minutes; later runs start in seconds. When the command returns, both containers are launching.

---

Step 5 - Confirm it is healthy

Ask the gateway for the state of every component in the deployment. The gateway lets you project just the fields you care about by listing them after the resource - here, each component's name, role, state, and a one-line status:

curl -s http://mf-api-gateway:9090/api/application-state/v1/*/name,role,state,info

A healthy system responds like this - one entry per component, every one FULLY_OPERATIONAL:

[
    { "name": "mf-mds-consolidated", "role": "ACTIVE", "state": "FULLY_OPERATIONAL", "info": "All constituents fully operational" },
    { "name": "mf-eta-simulator",    "role": "ACTIVE", "state": "FULLY_OPERATIONAL", "info": "All constituents fully operational" }
]

You are looking for state: FULLY_OPERATIONAL on every component, including the mf-eta-simulator. If you see that, your Elastic MDS is up. (Drop the /name,role,state,info suffix to see the full detail for each component - host, image, memory and CPU stats, and its state history.)

If the command returns nothing or connection-refused, give it another few seconds (the first startup does the most work), then retry. Persistent failures usually trace back to Step 1 (image access) - check the container logs with docker compose logs.

---

Step 6 - Watch the data

The sample applications ship in the MetaFluent JMS SDK. Clone it - the stable branch tracks the current demo milestone - and run the prebuilt subscriber (no build needed), asking for a single instrument - here, Vodafone on the simulated RDF service:

git clone --depth 1 -b stable git@github.com:MetaFluent/jms-sdk.git
cd jms-sdk
java -cp "bin/SimpleSubscriberApplication.jar:lib/*" \
     com.metafluent.examples.simplesub.SimpleSubscriber \
     -connect localhost:8900 -context com.metafluent.jms_context.mds RDF.VOD.L

You will see an Image: line - a full snapshot of the instrument's current field values - followed by UPDATE: lines as the simulated data changes. Press Ctrl+C to stop.

To learn the subscription model - contexts, topics, message types, and how your existing MetaFluent v5 JMS code carries over unchanged - see JMS Application Development.

---

Step 7 - Stop the system

From the consolidated directory:

docker compose down

For a completely clean slate before a fresh run, also clear the working directories:

rm -rf logs/* data/*

---

Where to go next

• Architecture: Basics - the mental model: what just happened, and the handful of concepts everything builds on.
• JMS Application Development - write your own subscribing or publishing application. If you have MetaFluent v5 code, start here - it still works.
• Deployment: Basics - how a real deployment differs from this single-host demo, and how to get there at your own pace.
• Operations: Monitoring & Diagnostics - seeing what a running system is doing.

---

After the demo: running it for real

This single-host setup is ideal for seeing Elastic MDS work and getting comfortable with it. When you move toward a real deployment, you do not have to change how you think about the system - the same services simply run across more than one machine, and the parts that carry the most load can be given more capacity. Elastic MDS is designed to grow with you, a step at a time; you are never forced to adopt the whole picture at once. Deployment: Basics lays out the options and helps you choose the smallest one that fits.