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
• Docker Image Versioning and Pulling
• 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 

Installation Steps

Clone the Repository

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

Then go through 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 example.env file to a .env file in the project root directory (where package.json is located).

cp example.env .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 example.env 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

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

Use Docker Compose in Development Cycle

For development, use the following steps:

• Step 1: Stop the running Application:

  docker compose down

• Step 2: Pull the Latest Source Code Changes:

  git pull origin main

• Step 3: Rebuild and Restart the Application:

  docker compose up --build

This will:

• Stop the running containers.
• Pull the latest source code changes.
• Rebuild and restart the application.

🚀 Install GolangCI-Lint

To install GolangCI-Lint, follow these steps:

🔹 Linux & macOS

Run the following command:

curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.54.2

Ensure $(go env GOPATH)/bin is in your PATH:

export PATH=$(go env GOPATH)/bin:$PATH

🔹 Windows

Use scoop (recommended):

scoop install golangci-lint

Or Go install:

go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

🔹 Verify Installation

Run:

golangci-lint --version

🛠 Linting & Fixing Code

🔹 Check for Issues

make check-lint

🔹 Auto-Fix Issues

make fix-lint

🔹 Run Both

make lint

Docker Image Versioning and Pulling

If you’d like to work with the Docker images for the KubestellarUI project, here’s how you can use the latest and versioned tags:

1. Frontend Image:

   • Tag: quay.io/kubestellar/ui:frontend
   • Latest Version: latest
   • Specific Version (Commit Hash): frontend-<commit-hash>

2. Backend Image:

   • Tag: quay.io/kubestellar/ui:backend
   • Latest Version: latest
   • Specific Version (Commit Hash): backend-<commit-hash>

How to Pull the Latest Images:

• Frontend Image:

  docker pull quay.io/kubestellar/ui:frontend

• Backend Image:

  docker pull quay.io/kubestellar/ui:backend

How to Pull Specific Version (Commit Hash):

If you want to pull an image for a specific version (e.g., commit hash), use:

• Frontend Image with Version:

  docker pull quay.io/kubestellar/ui:frontend-abcd1234

• Backend Image with Version:

  docker pull quay.io/kubestellar/ui:backend-abcd1234

Accessing the Application

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