Read more about KubeStellar

Check out the main KubeStellar project

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.

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

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

• Version: 1.23.4
• Download Link: Golang Downloads

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

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

• 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

• 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

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

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

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

Environment Variables

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

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.

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.

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

• Download Link: Docker Downloads

Docker Compose is configured to use environment variables with sensible defaults. You can customize the configuration by:

Option 1: Using a .env file (Recommended for persistent configuration)

Create a .env file in the project root directory:

cp .env.example .env

Example .env file for Docker Compose:

# Frontend Configuration
VITE_BASE_URL=http://localhost:4000
VITE_SKIP_PREREQUISITES_CHECK=true
VITE_APP_VERSION=0.1.0
NGINX_HOST=localhost
BACKEND_URL=http://localhost:4000
FRONTEND_PORT=5173

# Backend Configuration
BACKEND_PORT=4000
CORS_ALLOWED_ORIGIN=http://localhost:5173

# Redis Configuration
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_IMAGE=ghcr.io/kubestellar/ui/redis:latest
REDIS_CONTAINER_NAME=kubestellar-redis

# Example configurations for different environments:
# For production:
# VITE_BASE_URL=https://api.yourapp.com
# NGINX_HOST=yourapp.com
# BACKEND_URL=https://api.yourapp.com
# FRONTEND_PORT=80

# For staging:
# VITE_BASE_URL=https://staging-api.yourapp.com
# NGINX_HOST=staging.yourapp.com
# BACKEND_URL=https://staging-api.yourapp.com

Option 2: Using system environment variables

Set environment variables in your shell:

export VITE_BASE_URL=https://api.myapp.com
export NGINX_HOST=myapp.com
export BACKEND_URL=https://api.myapp.com
export FRONTEND_PORT=8080

Option 3: Inline environment variables

VITE_BASE_URL=https://api.myapp.com NGINX_HOST=myapp.com docker compose up

Frontend Variables:

• VITE_BASE_URL - Base URL for API calls (default: http://localhost:4000)
• VITE_SKIP_PREREQUISITES_CHECK - Skip prerequisites check (default: true)
• VITE_APP_VERSION - Application version (default: 0.1.0)
• NGINX_HOST - Nginx server name (default: localhost)
• BACKEND_URL - Backend URL for proxy (default: http://localhost:4000)
• FRONTEND_PORT - Frontend port mapping (default: 5173)

Backend Variables:

• BACKEND_PORT - Backend port mapping (default: 4000)
• CORS_ALLOWED_ORIGIN - CORS allowed origin (default: http://localhost:5173)
• REDIS_HOST - Redis host (default: localhost)
• REDIS_PORT - Redis port (default: 6379)

Redis Variables:

• REDIS_IMAGE - Redis Docker image (default: ghcr.io/kubestellar/ui/redis:latest)
• REDIS_CONTAINER_NAME - Redis container name (default: kubestellar-redis)

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

With custom ports:

FRONTEND_PORT=8080 BACKEND_PORT=3000 docker compose up

With production-like settings:

VITE_BASE_URL=https://api.production.com NGINX_HOST=production.com docker compose up

Using a specific Redis image:

REDIS_IMAGE=redis:7-alpine docker compose up

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. ✅

1. Backend API: http://localhost:4000 (or custom port if BACKEND_PORT is set)
2. Frontend UI: http://localhost:5173 (or custom port if FRONTEND_PORT is set)

• Username: admin
• Password: admin