Prerequisites
Check the status of your Minikube cluster:minikube start
Verify that your current context is `minikube`:minikube status
### 2. Preflight: Meshery Authentication Commands such as `mesheryctl connection create` call Meshery Server's API, so they need a running Meshery Server and a signed-in session. Do not sign in yet. The out-of-cluster steps below tell you to run `mesheryctl system login` after Meshery starts. See [Authenticate with Meshery via CLI](/guides/mesheryctl/authenticate-with-meshery-via-cli/). # In-cluster Installation ## Installation: Install Meshery on Kubernetes Using `mesheryctl` To install Meshery inside your Minikube cluster, run:kubectl config current-context
This command deploys the Meshery Helm chart into the `meshery` namespace. To verify the deployment, run:mesheryctl system start -p kubernetes
After deployment, reach Meshery UI through port forwarding:helm list -A -n meshery
For details, see the [port-forwarding](/reference/mesheryctl/system/dashboard/) guide. Meshery Server running in the cluster connects to it automatically. If the connection does not appear, sign in and create it yourself:mesheryctl system dashboard --port-forward
`mesheryctl connection create --type minikube` flattens your kubeconfig (`~/.kube/config`), writes it to `~/.meshery/kubeconfig.yaml`, and uploads it to Meshery Server. It replaces the deprecated `mesheryctl system config minikube`.mesheryctl connection create --type minikube
## Installation: Using Helm
You can also deploy Meshery directly with the Helm CLI. See the [Helm Installation](/installation/kubernetes/helm/) guide.
# Out-of-cluster Installation
To install Meshery on Docker (out-of-cluster) and connect it to your Minikube cluster, follow these steps.
## Installation: Install Meshery on Docker
Start Meshery on Docker:
This command starts Meshery in Docker containers. To verify that Meshery is running, run:mesheryctl system start -p docker
Meshery UI is available on your local machine at `http://localhost:9081`. Sign in with `mesheryctl system login`, then connect Meshery to your Minikube cluster. If you use the Docker driver, complete the steps in [Minikube Docker Driver Users](#minikube-docker-driver-users) first.docker ps
### Minikube Docker Driver Users If you run Minikube with the [Docker driver](https://minikube.sigs.k8s.io/docs/drivers/docker/), both Minikube and Meshery run in Docker containers, and you need a few extra steps so that Meshery can reach your cluster. First, put the Meshery and Minikube containers on the same Docker networks:mesheryctl connection create --type minikube
docker network connect bridge meshery-meshery-1
Next, update the Kubernetes API server address in your kubeconfig before you run `mesheryctl connection create --type minikube`, as described below. #### Next Step: Update the Kubernetes API Server Address for Meshery Access Because both Meshery and Minikube run in containers, the Meshery container cannot use the `localhost` address that Docker forwards the API server port to. Change the API server address in your kubeconfig to Minikube's own IP address instead. To get the Minikube IP, run `minikube ip`. The API server listens on port `8443` inside the Minikube container by default. Open your kubeconfig (`~/.kube/config`) in an editor and change the `server` field of the `minikube` cluster entry:docker network connect minikube meshery-meshery-1
Then connect Meshery to your cluster:server: https://{minikubeIP}:8443
**Note**: Instead of running `mesheryctl connection create`, you can upload your kubeconfig in Meshery UI, as described next. # Uploading Configuration File in the Meshery Web UI **Note**: Meshery can connect to your Minikube cluster only when Meshery itself runs locally, on Kubernetes or Docker. The hosted [Meshery Playground](https://playground.meshery.io/) cannot reach a cluster on your machine. **To upload your kubeconfig after you start Meshery locally**: 1. In the Meshery UI, navigate to **Lifecycle** from the menu on the left. 2. Select **Connections**. 3. Click **Create Connection** and choose **Kubernetes**. 4. In the **Import Kubeconfig** step, upload your kubeconfig file and select the contexts to import. 5. Review the import and confirm it. For details, see [Registering a Connection](/guides/infrastructure-management/registering-a-connection/). **Note**: If you get a connection refused error when you upload your kubeconfig, change your cluster's server URL to Minikube's external API address, as described in [Minikube Docker Driver Users](#minikube-docker-driver-users). ## Troubleshooting Meshery Installation If you run into problems during installation, see [Troubleshooting Meshery Installations](/guides/troubleshooting/installation/#setting-up-meshery-using-kind-or-minikube). # Post-Installation Steps Verify the health of your Meshery deployment with mesheryctl system check.mesheryctl connection create --type minikube
Once Meshery is running, mesheryctl system start opens Meshery UI in your default browser. On Docker, Meshery UI listens at http://localhost:9081 by default. On Kubernetes, mesheryctl opens the address of the meshery service in the meshery namespace, which the Helm chart creates as a LoadBalancer service on port 9081.
To open Meshery UI in your default browser at any time, run:
mesheryctl system dashboard
If your cluster does not give the meshery service a reachable address, forward a local port to Meshery instead. By default, mesheryctl listens on local port 9081; use -p to choose another port.
mesheryctl system dashboard --port-forward
You can also port-forward with kubectl:
kubectl port-forward svc/meshery 9081:9081 --namespace meshery
Connected.You can customize the callback URL that your Meshery Provider redirects to after sign-in. This helps when Meshery runs behind several layers of networking infrastructure.
For production deployments, we recommend that you expose Meshery UI through a reverse proxy or a load balancer. A custom callback URL makes sure that sign-in completes even when requests pass through several routing layers.
Note: For production deployments, use a Remote Provider so that you control which identity providers can sign users in. Learn more about this in the Extensibility: Providers guide.
To set a custom callback URL, set the MESHERY_SERVER_CALLBACK_URL environment variable when you start Meshery:
MESHERY_SERVER_CALLBACK_URL=https://custom-host mesheryctl system start
On Kubernetes, Meshery UI is then available at the EXTERNAL-IP of the meshery service. Run kubectl get svc meshery -n meshery to find it.