<p align="center"> <img alt="KubeStellar Logo" width="250px" src="frontend/public/Kubestellar-logo.png" /> </p> <h2 align="center">Multi-cluster Configuration Management for Edge, Multi-Cloud, and Hybrid Cloud Systems</h2> <p align="center"> <strong> <a href="https://kubestellar.io/">Read more about KubeStellar</a> </strong> </p>

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.

<a href="https://cloud-native.slack.com/archives/C097094RZ3M"> <img alt="Join Slack" src="https://img.shields.io/badge/KubeStellar-Join%20Slack-blue?logo=slack"> </a> <a href="https://deepwiki.com/kubestellar/ui"> <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"> </a>

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 Installation Guide: Guide

6. Golang Migrate

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

Installation Steps

Clone the Repository

git clone https://github.com/kubestellar/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_PROMETHEUS_URL=http://localhost:19090
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_PROMETHEUS_URL | Defines the Prometheus URL | http://localhost:19090 | | 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: Create .env File for Backend Configuration

To configure the backend, copy the .env.example file to a .env file in the backend/ directory.

cd backend/

cp .env.example .env

Example .env file:

REDIS_HOST=localhost
REDIS_PORT=6379
CORS_ALLOWED_ORIGIN=http://localhost:5173
DATABASE_URL=postgres://authuser:authpass123@localhost:5400/authdb?sslmode=disable
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
PORT=4000
GIN_MODE=debug

[!NOTE] Make sure to update the values according to your local environment setup, especially the DATABASE_URL and JWT_SECRET for security reasons.

Step 4: 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 5: 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