quick-start.md

🪄 Create an MDAI Engine instance locally 🪄

NOTE: These docs are for MDAI Engine installation on your local machine. We are updating documentation frequently. Thank you for your patience

Quick Start Guide

Setup the MDAI Engine locally

You are going to learn to do the following in less than five minutes:

• Set up and run a local instance of MDAI Engine
• Send telemetry to the MDAI Engine
• Access MDAI Engine Console to verify data flowing through the MDAI Engine.

Prerequisites

System Dependencies

• These docs assume that you have homebrew installed.
• If you're using MacOS, you'll also need XCode Commandline Tools installed.
• You will also need to have Kubernetes installed.

Automated installation

Our automated installation process is setting up all the required dependencies like

• Docker
• Kind cluster
• Npm
• Aws CDK
• Go
• Helm

Note: Once the Engine installed your k8s context will be switched automatically to new cluster.

Here are installation steps:

1. Pull down the latest from the MDAI infrastructure installation repo
2. Install kind for local cluster management using docker containers
3. Run automated installation script

make -f ./make/Makefile-local-recipes create-mdai

Other steps: While we install docker, you also need to ensure that the docker process is running. You can simply open the Docker app or start the Docker process to ensure the local runs flawlessly.

Automated uninstall

Make sure your k8s context is set to kind-mdai-local cluster:

kubectl config get-contexts

Switch the context if needed:

kubectl cluster-info --context kind-mdai-local

Run automated de-installation script

 make -f ./make/Makefile-local-recipes delete-mdai

If you want to remove all helm artifacts installed (you don't use it your other local setup), run the following

 make -f ./make/Makefile-local-recipes delete-mdai-all

Manual pre-req installations

• Install Go (1.20 or higher).
• GOBIN environment variable is set; if unset, initialize it appropriately, for example:

export GOBIN=${GOBIN:-$(go env GOPATH)/bin}

• Install npm
• Install aws-cdk
• Install docker
• Install kind for local cluster management using docker containers

Setup Environment

1. Create a cluster where the Engine can be installed. For our example, we'll use kind.

   <!--  Create cluster -->
   kind create cluster --name mdai-local
   
   <!-- Check that your cluster is up and running -->
   kind get clusters
   

2. Setup and configure a local instance of the MDAI Engine

   make local-deploy
   kubectl-config
   

3. Ensure your cluster is up and running.

   kubectl get pods
   

   _Note: the pod that starts with mydecisive-engine-ui-_*

4. Enable port forwarding from cluster to localhost

   <!-- Example kubectl port-forward mydecisive-engine-ui-578f644b7-k9q47 5173:5173 -->
   
   kubectl port-forward <POD_NAME> <PORT>:<PORT>
   

5. View the MDAI Console at http://localhost:5173 🐙🎉

Generate and Collect telemetry

1. Install OpenTelemetry's telemetrygen utility.

   go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest
   

2. Send Telemetry to the collector

   $GOBIN/telemetrygen traces --otlp-insecure --traces 3
   

3. Optional: Add a cronjob to schedule telemetry at a cadence

   TODO: command goes here!
   

Validate data flow

1. View the local MDAI console
2. As telemetry flows through the engine, you will see counts increase in the console, color-coded by telemetry type. 🐙🎉

Note: Data flowing to debug exporters are not counted towards data flow totals in the right sidebar