Running Magda on Minikube (published chart, no build required)

This guide sets up a local Magda instance on minikube using the published Helm chart — you don’t need to clone the repository or build any Docker images. It’s aimed at evaluating Magda or trying it out locally.

Setting up a developer/debug environment (building images, deploying the chart from a source checkout) is a different, heavier workflow. For thorough end-to-end verification of a release, see the End-to-End Full Cluster Deployment Test, which is written for contributors.

Magda is installed into its own magda namespace throughout.

Prerequisites

Install these (via Homebrew or your package manager of choice):

  1. Docker — used as the minikube driver
  2. minikube
  3. kubectl
  4. helm (v3)

Optional, but handy for watching pods start up:

Step 1: Start minikube

A default Magda install runs the full stack (search, semantic search, embedding API, PDF/CSV indexers, PostgreSQL, MinIO and OpenSearch) — around two dozen pods. Give the cluster enough resources:

minikube start --driver=docker --memory=16384 --cpus=4 --disk-size=60g

Minimum is roughly 8 GB memory / 2 CPUs, but the full stack is happier with more. On a constrained machine, see the chart’s values.yaml for how to disable optional components (for example, the semantic-search stack).

Step 2: Install the published chart

kubectl create namespace magda
helm install magda oci://ghcr.io/magda-io/charts/magda --version <VERSION> --timeout 9999s -n magda

Replace <VERSION> with the release you want — see the latest release (for example, 6.1.1). Installing with default values deploys the full stack.

Why --timeout 9999s? A first-time full-stack install runs post-install hooks (database migrations) that wait for OpenSearch, PostgreSQL and MinIO to come up. On a fresh cluster this can take longer than Helm’s default 5-minute timeout, and without the flag helm install may report failed post-install: timed out waiting for the condition even though the deployment is still coming up correctly. The long timeout lets Helm wait it out and report success.

Since v2, Magda’s Helm charts are published to the GitHub Container Registry: oci://ghcr.io/magda-io/charts.

Step 3: Wait for the pods to be ready

kubectl get pods -n magda -w

The full install brings up ~24 pods and can take several minutes on first run (image pulls, database migrations, OpenSearch cluster formation). A few early restarts on the indexer and semantic-indexer pods are normal — they retry until OpenSearch is accepting connections. Once things settle, nothing should remain outside Running/Completed:

kubectl get pods -n magda --no-headers | grep -vE "Running|Completed"
# should print nothing

Step 4: Access Magda in your browser

The lowest-friction way to reach the local instance is to port-forward the gateway (which fronts the whole platform):

kubectl port-forward -n magda svc/gateway 8080:80

Then open http://localhost:8080 in your browser. You can search and browse the catalogue straight away — no sudo, LoadBalancer or DNS setup required.

Next steps

Cleaning up

# remove Magda but keep the cluster
helm uninstall magda -n magda
kubectl delete namespace magda

# or remove the whole minikube cluster
minikube delete

Reinstalling on the same cluster? minikube’s default hostpath storage provisioner keys volume directories by namespace and PVC name, so deleting the magda namespace does not always erase the underlying data on the node. Reusing that stale data on a fresh install causes hard-to-diagnose failures — most notably MinIO crash-looping with Unable to initialize config system: Invalid credentials, because the volume still holds config encrypted with the previous install’s secrets. For a genuinely clean reinstall, either run minikube delete and start fresh, or clear the leftover data on the node:

minikube ssh -- 'sudo rm -rf /tmp/hostpath-provisioner/magda'