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
• Migration Commands

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

6. Golang Migrate

• Make sure you have installed 'golang-migrate' cli tool which helps in database migration
• Installation Guide: Install

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 frontend/ directory (where package.json is located).

cd frontend/

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.

Step 3: Run PostgreSQL and Redis with Docker Compose

To run PostgreSQL and Redis services:

# Navigate to the backend directory
cd backend

# Start PostgreSQL and Redis services in detached mode
docker compose up -d

# Verify that services are running
docker ps

This will start:

• PostgreSQL on port 5432 (for persistent data storage)
• Redis on port 6379 (for caching WebSocket updates)

Both services are configured with appropriate volumes to persist data between restarts.

Step 3: Install and Run the Backend

Make sure you are in the root directory of the project

cd backend

go mod download

make migrate-up #for keeping our database in sync with changes in sql code of project(only use when you've added/updated migration files)

# run this only when DB got changes without migration
# it forces the migration version(in local) to match with DB state
make migrate-force

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

cd frontend

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: Environment Configuration (Optional)

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 frontend/ directory:

cd frontend/

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

Note

All environment variables have default values, so the application will work without any configuration. The defaults are suitable for local development.

Available Environment Variables

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)

Step 3: 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

Step 4: Running with Custom Configuration

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

Accessing the Application

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)

Migration Commands

cd backend
make migrate-up #for keeping our database in sync with changes in sql code
make migrate-down #rollback to previous 1 migration version(1 by default) and can specify if needed more than 1
make create-migration #create new migration file
make migrate-force # Force set migration version (use if out of sync)

Dashboard Default Login Credentials

• Username: admin
• Password: admin

Note

If you're encountering errors while setting up the Kubestellar UI, even after correctly following the guide, try pruning the Docker images and containers related to the KS core.
Rebuild them and perform a restart.

This resolves almost 80% of issues caused by overridden changes during installation on existing systems.

Contributors