From 19fe3789b5801e8f51019c9481250465f36a2571 Mon Sep 17 00:00:00 2001 From: SethSterling22 Date: Wed, 18 Mar 2026 05:09:41 +0000 Subject: [PATCH 1/2] Update Readme --- README.md | 70 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 50 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 4c271be..31cc9f6 100644 --- a/README.md +++ b/README.md @@ -12,47 +12,77 @@ All the documentation for the MINT framework can be found in the [MINT documenta To test the MINT services on your local machine, we **strongly** recommend using the [microk8s](https://microk8s.io/) Kubernetes distribution. Follow the instructions in the [microk8s documentation](https://microk8s.io/#install-microk8s) to install microk8s on your machine. -### Microk8s installation +### Microk8s Installation and Setup Tested on MacOS (arm64) and microk8s 1.28/stable. Tested on Ubuntu 22.04 (amd64) and microk8s 1.28/stable. Install the microk8s using the following command: + +```bash +sudo snap install microk8s --classic --channel=1.35 +``` + +Give permissions: + ```bash -$ microk8s install --memory 8 -Support for 'multipass' needs to be set up. Would you like to do that now? [y/N]: y +sudo usermod -a -G microk8s $USER +mkdir -p ~/.kube +chmod 0700 ~/.kube +sudo chown -R $USER ~/.kube +newgrp microk8s ``` Enable required addons: ```console -$ microk8s enable dns -$ microk8s enable dashboard -$ microk8s enable hostpath-storage -$ microk8s enable ingress +microk8s enable dns +microk8s enable dashboard +microk8s enable hostpath-storage +microk8s enable ingress ``` +### Test Microk8s + To test, list the existing resources. It should be list multiple services, deployments, and pods. Please wait until all the resources are up and running. ```bash -$ microk8s kubectl get all --all-namespaces +microk8s kubectl get all --all-namespaces ``` Verify the node status ```bash -$ microk8s kubectl get nodes +microk8s kubectl get nodes +``` + + +### Install Portainer for MicroK8s (Optional) + +Portainer serves as a supervisor of your pods, where you can see and configure them graphically. + +```bash +microk8s enable community +microk8s enable portainer ``` +To see the status: + +```bash +microk8s status --wait-ready +microk8s kubectl get svc -n portainer +``` + +Serves as default on port `30779` with https. ### MINT services installation Use the following commands to install the MINT services: ```bash -$ microk8s helm repo add mint https://mintproject.github.io/mint -$ microk8s helm repo update -$ microk8s helm install testing-mint mint/MINT --namespace mint --create-namespace +microk8s helm repo add mint https://mintproject.github.io/mint +microk8s helm repo update +microk8s helm install testing-mint mint/MINT --namespace mint --create-namespace ``` If you using MacOS Silicon, you need to install the `arm64` version of the postgresql database. @@ -60,9 +90,9 @@ If you using MacOS Silicon, you need to install the `arm64` version of the postg **WARNING:** The arm64 image has not been tested and may not work as expected. Please use it at your own risk. ``` -$ microk8s helm repo add mint https://mintproject.github.io/mint -$ microk8s helm repo update -$ microk8s helm install testing-mint mint/mint --namespace mint --create-namespace --set arm_support=true +microk8s helm repo add mint https://mintproject.github.io/mint +microk8s helm repo update +microk8s helm install testing-mint mint/mint --namespace mint --create-namespace --set arm_support=true ``` Helm will returns the URL to access the MINT services. You can use the following command to get the URL: @@ -85,14 +115,14 @@ http://datacatalog.mint.local If you are using microk8s on a VM, need to get the IP address of the VM to access the MINT services. You can use the following command to get the IP address of the VM: ```bash -$ microk8s kubectl get node -o json | jq '.items[].status.addresses[] | select(.type=="InternalIP") | .address' +microk8s kubectl get node -o json | jq '.items[].status.addresses[] | select(.type=="InternalIP") | .address' 10.211.59.16 ``` Then, edit the `/etc/hosts` file and add the following lines: ```bash -$ sudo vim /etc/hosts +sudo vim /etc/hosts ``` Add the following lines (replace the IP address with the IP address of the VM): @@ -115,9 +145,9 @@ Add the following lines (replace the IP address with the IP address of the VM): To remove the MINT services, use the following command: ```bash -$ helm uninstall mint -n mint -$ kubectl delete pvc --all -n mint -$ kubectl delete jobs --all -n mint +helm uninstall mint -n mint +kubectl delete pvc --all -n mint +kubectl delete jobs --all -n mint ``` or From 4fcc4bb538f6a707547f41dd60c29e1b2e02a096 Mon Sep 17 00:00:00 2001 From: SethSterling22 Date: Wed, 18 Mar 2026 06:21:30 +0000 Subject: [PATCH 2/2] improve readme --- README.md | 115 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 96 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 31cc9f6..6a141a6 100644 --- a/README.md +++ b/README.md @@ -17,24 +17,58 @@ To test the MINT services on your local machine, we **strongly** recommend using Tested on MacOS (arm64) and microk8s 1.28/stable. Tested on Ubuntu 22.04 (amd64) and microk8s 1.28/stable. +#### Before starting, ensure you have + +Sudo/Administrator access on the target machine. + +Snapd (for Linux) or Multipass/Docker Desktop (for Windows/macOS). + +Helm 3 (Included in MicroK8s). + +### Microk8s installation + Install the microk8s using the following command: +#### Linux (Ubuntu/Debian/CentOS) + +MicroK8s runs natively on Linux. This is the recommended environment for production-like testing. ```bash +# Install MicroK8s sudo snap install microk8s --classic --channel=1.35 -``` -Give permissions: - -```bash +# Fix Permissions (replace $USER if necessary) sudo usermod -a -G microk8s $USER mkdir -p ~/.kube chmod 0700 ~/.kube sudo chown -R $USER ~/.kube + +# Apply group changes without logging out newgrp microk8s ``` -Enable required addons: +#### MacOS (Intel & Apple Silicon) + +MicroK8s uses a lightweight VM via Multipass. + +Download the MicroK8s Installer for macOS. + +For Apple Silicon (M1/M2/M3), ensure you follow the ARM instructions in the "MINT Services" section. + + +#### Windows 10/11 + +Download the [MicroK8s Installer for Windows](https://canonical.com/microk8s/docs/install-windows). + +Ensure WSL2 is enabled. + +Use PowerShell to run commands (prefixing with microk8s if not aliased). + + + +### Cluster Setup & Addons + +Enable the core components required for MINT to route traffic and manage storage: ```console microk8s enable dns @@ -73,31 +107,44 @@ microk8s status --wait-ready microk8s kubectl get svc -n portainer ``` -Serves as default on port `30779` with https. ++ Access: `https://:30779` + ++ Default Port: `30779` (NodePort) + +--- ### MINT services installation Use the following commands to install the MINT services: +#### Option A: Standard x86_64 (Intel/AMD) + ```bash microk8s helm repo add mint https://mintproject.github.io/mint microk8s helm repo update microk8s helm install testing-mint mint/MINT --namespace mint --create-namespace ``` -If you using MacOS Silicon, you need to install the `arm64` version of the postgresql database. -**WARNING:** The arm64 image has not been tested and may not work as expected. Please use it at your own risk. +#### Option B: ARM64 (Apple Silicon / ARM Servers) -``` +```bash microk8s helm repo add mint https://mintproject.github.io/mint microk8s helm repo update -microk8s helm install testing-mint mint/mint --namespace mint --create-namespace --set arm_support=true +microk8s helm install testing-mint mint/MINT --namespace mint --create-namespace --set arm_support=true ``` -Helm will returns the URL to access the MINT services. You can use the following command to get the URL: +If you using MacOS Silicon, you need to install the `arm64` version of the postgresql database. + +**WARNING:** The arm64 image has not been tested and may not work as expected. Please use it at your own risk. + +--- + +### Networking & Remote Access -```txt +Helm will returns the URL to access the MINT services after installation. + +```bash The MINT system has been installed! Please remember to edit your `/etc/hosts/` @@ -112,20 +159,34 @@ http://mic.mint.local http://datacatalog.mint.local ``` +Since MINT uses subdomains (e.g., mint.local), you must map the server's IP to these hostnames on your local computer's host file. + + +1. Identify Server IP + + If you are using microk8s on a VM, need to get the IP address of the VM to access the MINT services. You can use the following command to get the IP address of the VM: ```bash microk8s kubectl get node -o json | jq '.items[].status.addresses[] | select(.type=="InternalIP") | .address' -10.211.59.16 ``` -Then, edit the `/etc/hosts` file and add the following lines: +If accessing via Public IP (Cloud), use that IP instead. + +2. Update Hosts File (On your Personal Computer) + +| OS | Path | Command | +| --- | --- | --- | +| Linux/macOS | /etc/hosts | sudo nano /etc/hosts | +| Windows | C:\Windows\System32\drivers\etc\hosts | Open Notepad as Administrator | + ```bash sudo vim /etc/hosts ``` -Add the following lines (replace the IP address with the IP address of the VM): + +Add the following block (Replace `10.211.59.16` with your Server/VM IP): ```text 10.211.59.16 mint.local @@ -140,14 +201,19 @@ Add the following lines (replace the IP address with the IP address of the VM): 10.211.59.16 endpoint.models.mint.local ``` -### MINT services removal +### MINT services removal & reset To remove the MINT services, use the following command: ```bash -helm uninstall mint -n mint -kubectl delete pvc --all -n mint -kubectl delete jobs --all -n mint +microk8s helm uninstall testing-mint -n mint +microk8s kubectl delete pvc --all -n mint +``` + +Full MicroK8s Reset (Destructive): + +```bash +microk8s reset ``` or @@ -156,6 +222,17 @@ or bash uninstall.sh ``` +### Available Services + +Once the pods are "Running" (check via Portainer or microk8s kubectl get pods -n mint), you can access: + + ++ Main Interface: http://mint.local + ++ Data Catalog: http://datacatalog.mint.local + ++ Model Catalog (MIC): http://mic.mint.local + ## Developer documentation This repository contains the helm charts for the MINT services. The helm charts are used to deploy the services in a Kubernetes cluster. The helm charts are organized in the following folders: