Multi-cluster Configuration Management for Edge, Multi-Cloud, and Hybrid Cloud

Read more about KubeStellar

Check out the main KubeStellar project

KubestellarUI Setup Guide

Welcome to KubestellarUI! This guide will help you set up the KubestellarUI application on your local machine after cloning the repository for development. The application consists of two main parts:

1. Frontend: Built with React and TypeScript
2. Backend: Built with Golang using the Gin framework.

Contents

• Prerequisites
• Installation Steps
  • Local Setup
  • Local Setup with Docker Compose
• Accessing the Application

Prerequisites

Before you begin, ensure that your system meets the following requirements:

1. Golang

• Version: 1.23.4
• Download Link: Golang Downloads

2. Node.js and npm

• Node.js Version: ≥ 16.x.x
• npm Version: Comes bundled with Node.js
• Download Link: Node.js Downloads

Note

You can use nvm to manage multiple Node.js versions.

3. Git

• Ensure Git is installed to clone the repository
• Download Link: Git Downloads

4. Kubernetes Clusters

• Ensure you have access to a Kubernetes clusters setup with Kubestellar Getting Started Guide & Kubestellar prerequisites installed

• Kubestellar guide: Guide

  [!NOTE] If you're running on macOS, you may need to manually add a host entry to resolve its1.localtest.me to localhost using echo "127.0.0.1 its1.localtest.me" | sudo tee -a /etc/hosts

5. Make and Air

• Make sure you have "make" installed to directly execute the backend script via makefile
• Air helps in hot reloading of the backend
• Air guide: Guide

Installation Steps

Clone the Repository

git clone https://github.com/your-github-username/ui.git

cd ui

Then go through one of the setup options below:

• Local Setup
• Local Setup with Docker Compose

Local Setup

Step 1: Create .env File for Frontend Configuration

To configure the frontend, copy the .env.example file to a .env file in the project root directory (where package.json is located).

cp .env.example .env

Example .env file:

VITE_BASE_URL=http://localhost:4000
VITE_APP_VERSION=0.1.0
VITE_GIT_COMMIT_HASH=$GIT_COMMIT_HASH

Note

This is because .env files are intended to be a personal environment configuration file. The included .env.example in the repo is a standard that most other node projects include for the same purpose. You rename the file to .env and then change its contents to align with your system and personal needs.

Tracking Application Version and Git Commit Hash

KubestellarUI uses environment variables to track the app version and the current Git commit hash.

Environment Variables

Variable	Purpose	Example
VITE_BASE_URL	Defines the base URL for API calls	http://localhost:4000
VITE_APP_VERSION	Defines the current application version	0.1.0
VITE_GIT_COMMIT_HASH	Captures the current Git commit hash	(Set during build)

Step 2: Run Redis Container (Optional)

KubestellarUI uses Redis for caching real-time WebSocket updates to prevent excessive Kubernetes API calls.

Run Redis using Docker:

docker run --name redis -d -p 6379:6379 redis

Verify Redis is running:

docker ps | grep redis

Step 3: Install and Run the Backend

Make sure you are in the root directory of the project

cd backend

go mod download

# Option 1 : Start backend with hot reloading (recommended)
make dev

# Option 2 : Start backend without hot reloading
go run main.go

You should see output indicating the server is running on port 4000.

Step 4: Install and Run Frontend

Open another terminal and make sure you are in the root directory of the project.

npm install

npm run dev

You should see output indicating the server is running on port 5173.

Local Setup with Docker Compose

If you prefer to run the application using Docker Compose, follow these steps:

Step 1: Ensure Docker is Installed

• Download Link: Docker Downloads

Note

If you are using Docker Desktop, please enable host networking. To do so navigate to Settings > Resources > Network, and check the "Enable host networking" option. Finally, apply the changes and restart Docker Desktop.

Note

If you are using Compose V1, change the docker compose command to docker-compose in the following steps. Checkout Migrating to Compose V2 for more info.

Step 2: Run Services

From the project root directory

docker compose up --build

You should see output indicating the services are running.

To stop the application

docker compose down

---

Note for WSL Users 🐧

If you've successfully installed the KubeStellar but they are not detected by frontend, it might be due to a communication issue between Docker and WSL.

Here are a few steps to resolve it:

1. Open Docker Desktop settings and ensure WSL integration is enabled for your distribution (e.g., Ubuntu).
2. If the issue persists, consider uninstalling Docker Desktop from Windows and instead install Docker directly inside your WSL environment (e.g., Ubuntu).
3. After installing Docker inside WSL, reinstall the KubeStellar. This setup typically resolves the detection issues. ✅

Accessing the Application

1. Backend API: http://localhost:4000
2. Frontend UI: http://localhost:5173

Dashboard Default Login Credentials

• Username: admin
• Password: admin

Contributors