Deploy on Local using Helm Charts and Minikube

A step-by-step guide to deploying Hyperswitch locally using Helm and Minikube, with setup, access, cleanup, and troubleshooting instructions.

One-click setup

Copy and paste the below in your terminal. The script will check for missing prerequisites (kubectl, helm, curl, jq) and install any that are missing, spin up a local Kubernetes cluster, deploy Hyperswitch, configure a merchant account and business profile, add 4 dummy connectors (stripe_test, paypal_test, fauxpay, pretendpay), set up routing rules, and seed 50 test transactions across all connectors

bash <(curl -fsSL https://raw.githubusercontent.com/juspay/hyperswitch/refs/heads/main/scripts/hyperswitch-explore.sh)

Or review the deployment guide given below.

Part 1: Setting Up a Local Kubernetes Cluster with Minikube/OrbStack

Option 1: Setting Up a Local Kubernetes Cluster with Minikube

Step 1: Install Required Tools

a. kubectl

kubectl is the CLI for interacting with Kubernetes clusters. To install it, refer to the official guide: Install kubectl

b. Minikube

Minikube is a local Kubernetes cluster for development/testing. Install Minikube following the official documentation: Install Minikube

c. Helm

Helm is a package manager for Kubernetes applications. Install Helm using the instructions here: Install Helm

Step 2: Start Minikube

Start a Minikube cluster with sufficient resources:

minikube start --cpus=4 --memory=7900 --driver=docker

You can also use --driver=virtualbox or --driver=hyperkit depending on your system.

Verify the cluster is running:

kubectl get nodes

Option 2: Setting Up a Local Kubernetes Cluster using OrbStack (Only for macOS)

Step 1: Install Required Tools

brew install helm

brew install orbstack  # Download the OrbStack application

Step 2: Set Up Kubernetes in OrbStack

1. Open the OrbStack application.

2. Navigate to the Pods section.

3. Enable Kubernetes from the settings.

Part 2: Deploy Hyperswitch on Kubernetes Using Helm

Step 1: Add and Update the Hyperswitch Helm Repository

helm repo add hyperswitch https://juspay.github.io/hyperswitch-helm
helm repo update

Step 2: Install Hyperswitch

Install the Helm chart and create the namespace:

helm install hypers-v1 hyperswitch/hyperswitch-stack -n hyperswitch --create-namespace

Check the status of the pods:

kubectl get pods -n hyperswitch

That's it! Hyperswitch should be up and running on your Minikube Cluster🎉 🎉

Step 3: Accessing Services

Use the commands from the Step 2 (from above) for port-forwarding to access the services.

Access services at:

• App server: http://localhost:8080

• Control center: http://localhost:9000

• Hyperswitch Web: http://localhost:9050/HyperLoader.js

• Grafana: http://localhost:3000

• Vector: http://localhost:3103

• Mailhog: http://localhost:8025

Cleanup

To uninstall Hyperswitch and clean up the namespace:

helm uninstall hypers-v1 -n hyperswitch
kubectl delete namespace hyperswitch

Troubleshooting

View Pod Logs

kubectl logs <pod-name> -n hyperswitch

View Events

kubectl get events -n hyperswitch --sort-by='.metadata.creationTimestamp'