{"id":29865648,"url":"https://github.com/kubestellar/ui","last_synced_at":"2025-07-30T11:13:19.070Z","repository":{"id":268893717,"uuid":"905779686","full_name":"kubestellar/ui","owner":"kubestellar","description":"KubeStellar's User Interface","archived":false,"fork":false,"pushed_at":"2025-07-29T13:09:20.000Z","size":8809,"stargazers_count":56,"open_issues_count":118,"forks_count":153,"subscribers_count":10,"default_branch":"dev","last_synced_at":"2025-07-29T15:15:40.739Z","etag":null,"topics":["gitops","kubernetes","kubestellar","kubestellar-ui"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kubestellar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-19T14:02:54.000Z","updated_at":"2025-07-29T13:09:25.000Z","dependencies_parsed_at":"2025-01-23T21:25:52.317Z","dependency_job_id":"0a07015f-61bd-4d92-bfbd-47c7f51d0dd3","html_url":"https://github.com/kubestellar/ui","commit_stats":null,"previous_names":["kubestellar/ui"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/kubestellar/ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubestellar%2Fui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubestellar%2Fui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubestellar%2Fui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubestellar%2Fui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kubestellar","download_url":"https://codeload.github.com/kubestellar/ui/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubestellar%2Fui/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267713814,"owners_count":24132612,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gitops","kubernetes","kubestellar","kubestellar-ui"],"created_at":"2025-07-30T11:13:18.094Z","updated_at":"2025-07-30T11:13:19.052Z","avatar_url":"https://github.com/kubestellar.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"KubeStellar Logo\" width=\"250px\" src=\"frontend/public/Kubestellar-logo.png\" /\u003e\n\u003c/p\u003e\n\n\u003ch2 align=\"center\"\u003eMulti-cluster Configuration Management for Edge, Multi-Cloud, and Hybrid Cloud\u003c/h2\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e\n    \u003ca href=\"https://kubestellar.io/\"\u003eRead more about KubeStellar\u003c/a\u003e\n  \u003c/strong\u003e\n\u003c/p\u003e\n\n\u003e Check out the main [KubeStellar project](https://github.com/kubestellar/kubestellar)\n\n# KubestellarUI Setup Guide\n\nWelcome 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:\n\n1. **Frontend**: Built with React and TypeScript\n2. **Backend**: Built with Golang using the Gin framework.\n\n\u003ca href=\"https://cloud-native.slack.com/archives/C097094RZ3M\"\u003e \n  \u003cimg alt=\"Join Slack\" src=\"https://img.shields.io/badge/KubeStellar-Join%20Slack-blue?logo=slack\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://deepwiki.com/kubestellar/ui\"\u003e\n  \u003cimg src=\"https://deepwiki.com/badge.svg\" alt=\"Ask DeepWiki\"\u003e\n\u003c/a\u003e\n\n## Contents\n\n- [Prerequisites](#prerequisites)\n- [Installation Steps](#installation-steps)\n  - [Local Setup](#local-setup)\n  - [Local Setup with Docker Compose](#local-setup-with-docker-compose)\n- [Accessing the Application](#accessing-the-application)\n- [Migration Commands](#migration-commands)\n\n## Prerequisites\n\n**Before you begin, ensure that your system meets the following requirements:**\n\n### 1. Golang\n\n- **Version**: 1.23.4\n- **Download Link**: [Golang Downloads](https://golang.org/dl/)\n\n### 2. Node.js and npm\n\n- **Node.js Version**: ≥ 16.x.x\n- **npm Version**: Comes bundled with Node.js\n- **Download Link**: [Node.js Downloads](https://nodejs.org/en/download/)\n\n\u003e [!NOTE]\n\u003e You can use [nvm](https://github.com/nvm-sh/nvm) to manage multiple Node.js versions.\n\n### 3. Git\n\n- Ensure Git is installed to clone the repository\n- **Download Link**: [Git Downloads](https://git-scm.com/downloads)\n\n### 4. Kubernetes Clusters\n\n- Ensure you have access to a Kubernetes clusters setup with Kubestellar Getting Started Guide \u0026 Kubestellar prerequisites installed\n\n- **Kubestellar guide**: [Guide](https://docs.kubestellar.io/release-0.25.1/direct/get-started/)\n\n\u003e [!NOTE]\n\u003e If you're running on macOS, you may need to manually add a host entry to resolve `its1.localtest.me` to `localhost` using:\n\u003e\n\u003e ```bash\n\u003e echo \"127.0.0.1 its1.localtest.me\" | sudo tee -a /etc/hosts\n\u003e ```\n\n### 5. Make and Air\n\n- Make sure you have \"make\" installed to directly execute the backend script via makefile\n- Air helps in hot reloading of the backend\n- **Air Installation Guide**: [Guide](https://github.com/air-verse/air#installation)\n\n### 6. Golang Migrate\n\n- Make sure you have installed 'golang-migrate' cli tool which helps in database migration\n- **Golang-Migrate Installation Guide:** [Install](https://github.com/golang-migrate/migrate/tree/master/cmd/migrate)\n\n## Installation Steps\n\nClone the Repository\n\n```bash\ngit clone https://github.com/kubestellar/ui.git\n\ncd ui\n```\n\nThen go through one of the setup options below:\n\n- [Local Setup](#local-setup)\n- [Local Setup with Docker Compose](#local-setup-with-docker-compose)\n\n### Local Setup\n\n#### Step 1: Create `.env` File for Frontend Configuration\n\nTo configure the frontend, copy the `.env.example` file to a `.env` file in the `frontend/` directory (where `package.json` is located).\n\n```bash\ncd frontend/\n\ncp .env.example .env\n```\n\n**Example `.env` file:**\n\n```env\nVITE_BASE_URL=http://localhost:4000\nVITE_APP_VERSION=0.1.0\nVITE_GIT_COMMIT_HASH=$GIT_COMMIT_HASH\n```\n\n\u003e [!NOTE]\n\u003e 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.\n\n##### Tracking Application Version and Git Commit Hash\n\nKubestellarUI uses environment variables to track the app version and the current Git commit hash.\n\n**Environment Variables**\n\n| Variable               | Purpose                                 | Example                 |\n| ---------------------- | --------------------------------------- | ----------------------- |\n| `VITE_BASE_URL`        | Defines the base URL for API calls      | `http://localhost:4000` |\n| `VITE_APP_VERSION`     | Defines the current application version | `0.1.0`                 |\n| `VITE_GIT_COMMIT_HASH` | Captures the current Git commit hash    | (Set during build)      |\n\n#### Step 2: Run Redis Container (Optional)\n\nKubestellarUI uses Redis for caching real-time WebSocket updates to prevent excessive Kubernetes API calls.\n\n#### Step 3: Run PostgreSQL and Redis with Docker Compose\n\nTo run PostgreSQL and Redis services:\n\n```bash\n# Navigate to the backend directory\ncd backend\n\n# Start PostgreSQL and Redis services in detached mode\ndocker compose up -d\n\n# Verify that services are running\ndocker ps\n```\n\nThis will start:\n\n- PostgreSQL on port 5432 (for persistent data storage)\n- Redis on port 6379 (for caching WebSocket updates)\n\nBoth services are configured with appropriate volumes to persist data between restarts.\n\n#### Step 3: Create `.env` File for Backend Configuration\n\nTo configure the backend, copy the `.env.example` file to a `.env` file in the `backend/` directory.\n\n```bash\ncd backend/\n\ncp .env.example .env\n```\n\n**Example `.env` file:**\n\n```env\nREDIS_HOST=localhost\nREDIS_PORT=6379\nCORS_ALLOWED_ORIGIN=http://localhost:5173\nDATABASE_URL=postgres://authuser:authpass123@localhost:5400/authdb?sslmode=disable\nJWT_SECRET=your-super-secret-jwt-key-change-this-in-production\nPORT=4000\nGIN_MODE=debug\n```\n\n\u003e [!NOTE]\n\u003e Make sure to update the values according to your local environment setup, especially the `DATABASE_URL` and `JWT_SECRET` for security reasons.\n\n#### Step 4: Install and Run the Backend\n\nMake sure you are in the root directory of the project\n\n```bash\ncd backend\n\ngo mod download\n\nmake migrate-up #for keeping our database in sync with changes in sql code of project(only use when you've added/updated migration files)\n\n# run this only when DB got changes without migration\n# it forces the migration version(in local) to match with DB state\nmake migrate-force\n\n# Option 1 : Start backend with hot reloading (recommended)\nmake dev\n\n# Option 2 : Start backend without hot reloading\ngo run main.go\n```\n\nYou should see output indicating the server is running on port `4000`.\n\n#### Step 5: Install and Run Frontend\n\nOpen another terminal and make sure you are in the root directory of the project.\n\n```bash\ncd frontend\n\nnpm install\n\nnpm run dev\n```\n\nYou should see output indicating the server is running on port `5173`.\n\n### Local Setup with Docker Compose\n\nIf you prefer to run the application using Docker Compose, follow these steps:\n\n#### Step 1: Ensure Docker is Installed\n\n- **Download Link**: [Docker Downloads](https://www.docker.com/products/docker-desktop)\n\n\u003e [!NOTE]\n\u003e If you are using Docker Desktop, please enable host networking. To do so navigate to Settings \u003e Resources \u003e Network, and check the \"Enable host networking\" option. Finally, apply the changes and restart Docker Desktop.\n\n\u003e [!NOTE]\n\u003e If you are using Compose V1, change the `docker compose` command to `docker-compose` in the following steps.\n\u003e Checkout [Migrating to Compose V2](https://docs.docker.com/compose/releases/migrate/) for more info.\n\n#### Step 2: Environment Configuration (Optional)\n\nDocker Compose is configured to use environment variables with sensible defaults. You can customize the configuration by:\n\n**Option 1: Using a .env file** (Recommended for persistent configuration)\n\nCreate a `.env` file in the `frontend/` directory:\n\n```bash\ncd frontend/\n\ncp .env.example .env\n```\n\n**Example `.env` file for Docker Compose:**\n\n```bash\n# Frontend Configuration\nVITE_BASE_URL=http://localhost:4000\nVITE_SKIP_PREREQUISITES_CHECK=true\nVITE_APP_VERSION=0.1.0\nNGINX_HOST=localhost\nBACKEND_URL=http://localhost:4000\nFRONTEND_PORT=5173\n\n# Backend Configuration\nBACKEND_PORT=4000\nCORS_ALLOWED_ORIGIN=http://localhost:5173\n\n# Redis Configuration\nREDIS_HOST=localhost\nREDIS_PORT=6379\nREDIS_IMAGE=ghcr.io/kubestellar/ui/redis:latest\nREDIS_CONTAINER_NAME=kubestellar-redis\n\n# Example configurations for different environments:\n# For production:\n# VITE_BASE_URL=https://api.yourapp.com\n# NGINX_HOST=yourapp.com\n# BACKEND_URL=https://api.yourapp.com\n# FRONTEND_PORT=80\n\n# For staging:\n# VITE_BASE_URL=https://staging-api.yourapp.com\n# NGINX_HOST=staging.yourapp.com\n# BACKEND_URL=https://staging-api.yourapp.com\n```\n\n**Option 2: Using system environment variables**\n\nSet environment variables in your shell:\n\n```bash\nexport VITE_BASE_URL=https://api.myapp.com\nexport NGINX_HOST=myapp.com\nexport BACKEND_URL=https://api.myapp.com\nexport FRONTEND_PORT=8080\n```\n\n**Option 3: Inline environment variables**\n\n```bash\nVITE_BASE_URL=https://api.myapp.com NGINX_HOST=myapp.com docker compose up\n```\n\n\u003e [!NOTE]\n\u003e All environment variables have default values, so the application will work without any configuration. The defaults are suitable for local development.\n\n##### Available Environment Variables\n\n**Frontend Variables:**\n\n- `VITE_BASE_URL` - Base URL for API calls (default: `http://localhost:4000`)\n- `VITE_SKIP_PREREQUISITES_CHECK` - Skip prerequisites check (default: `true`)\n- `VITE_APP_VERSION` - Application version (default: `0.1.0`)\n- `NGINX_HOST` - Nginx server name (default: `localhost`)\n- `BACKEND_URL` - Backend URL for proxy (default: `http://localhost:4000`)\n- `FRONTEND_PORT` - Frontend port mapping (default: `5173`)\n\n**Backend Variables:**\n\n- `BACKEND_PORT` - Backend port mapping (default: `4000`)\n- `CORS_ALLOWED_ORIGIN` - CORS allowed origin (default: `http://localhost:5173`)\n- `REDIS_HOST` - Redis host (default: `localhost`)\n- `REDIS_PORT` - Redis port (default: `6379`)\n\n**Redis Variables:**\n\n- `REDIS_IMAGE` - Redis Docker image (default: `ghcr.io/kubestellar/ui/redis:latest`)\n- `REDIS_CONTAINER_NAME` - Redis container name (default: `kubestellar-redis`)\n\n#### Step 3: Run Services\n\nFrom the project root directory:\n\n```bash\ndocker compose up --build\n```\n\nYou should see output indicating the services are running.\n\nTo stop the application:\n\n```bash\ndocker compose down\n```\n\n#### Step 4: Running with Custom Configuration\n\n**With custom ports:**\n\n```bash\nFRONTEND_PORT=8080 BACKEND_PORT=3000 docker compose up\n```\n\n**With production-like settings:**\n\n```bash\nVITE_BASE_URL=https://api.production.com NGINX_HOST=production.com docker compose up\n```\n\n**Using a specific Redis image:**\n\n```bash\nREDIS_IMAGE=redis:7-alpine docker compose up\n```\n\n---\n\n\u003e [!NOTE]\n\u003e **For WSL Users 🐧**\n\u003e\n\u003e 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.\n\u003e\n\u003e Here are a few steps to resolve it:\n\u003e\n\u003e 1. Open Docker Desktop settings and ensure WSL integration is enabled for your distribution (e.g., Ubuntu).\n\u003e 2. If the issue persists, consider uninstalling Docker Desktop from Windows and instead install Docker **directly inside your WSL environment** (e.g., Ubuntu).\n\u003e 3. After installing Docker inside WSL, reinstall the KubeStellar. This setup typically resolves the detection issues. ✅\n\n### Accessing the Application\n\n1. **Backend API**: [http://localhost:4000](http://localhost:4000) (or custom port if `BACKEND_PORT` is set)\n2. **Frontend UI**: [http://localhost:5173](http://localhost:5173) (or custom port if `FRONTEND_PORT` is set)\n\n### Migration Commands\n\n```bash\ncd backend\nmake migrate-up #for keeping our database in sync with changes in sql code\nmake migrate-down #rollback to previous 1 migration version(1 by default) and can specify if needed more than 1\nmake create-migration #create new migration file\nmake migrate-force # Force set migration version (use if out of sync)\n```\n\n#### Dashboard Default Login Credentials\n\n- **Username: admin**\n- **Password: admin**\n\n\u003e [!NOTE]\n\u003e 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.  \n\u003e Rebuild them and perform a restart.\n\u003e\n\u003e This resolves almost 80% of issues caused by overridden changes during installation on existing systems.\n\n## Getting in touch\n\nThere are several ways to communicate with us:\n\n- Instantly get access to our documents and meeting invites at our [Join Us Page.](http://kubestellar.io/joinus)\n\n- The [`#kubestellar-dev` channel](https://cloud-native.slack.com/archives/C097094RZ3M) in the [Cloud Native Slack Workspace](https://communityinviter.com/apps/cloud-native/cncf).\n\n- Our mailing lists:\n  - [kubestellar-dev](https://groups.google.com/g/kubestellar-dev) for development discussions.\n  - [kubestellar-users](https://groups.google.com/g/kubestellar-users) for discussions among users and potential users.\n\n- Subscribe to the [community meeting calendar](https://calendar.google.com/calendar/event?action=TEMPLATE\u0026tmeid=MWM4a2loZDZrOWwzZWQzZ29xanZwa3NuMWdfMjAyMzA1MThUMTQwMDAwWiBiM2Q2NWM5MmJlZDdhOTg4NGVmN2ZlOWUzZjZjOGZlZDE2ZjZmYjJmODExZjU3NTBmNTQ3NTY3YTVkZDU4ZmVkQGc\u0026tmsrc=b3d65c92bed7a9884ef7fe9e3f6c8fed16f6fb2f811f5750f547567a5dd58fed%40group.calendar.google.com\u0026scp=ALL) for community meetings and events.\n  - The [kubestellar-dev](https://groups.google.com/g/kubestellar-dev) mailing list is subscribed to this calendar.\n\n- See recordings of past KubeStellar community meetings on [YouTube](https://www.youtube.com/@kubestellar)\n\n- See [upcoming](https://github.com/kubestellar/kubestellar/issues?q=is%3Aissue+is%3Aopen+label%3Acommunity-meeting) and [past](https://github.com/kubestellar/kubestellar/issues?q=is%3Aissue+is%3Aclosed+label%3Acommunity-meeting) community meeting agendas and notes.\n\n- Browse the [shared Google Drive](https://drive.google.com/drive/folders/1p68MwkX0sYdTvtup0DcnAEsnXElobFLS?usp=sharing) to share design docs, notes, etc.\n  - Members of the [kubestellar-dev](https://groups.google.com/g/kubestellar-dev) mailing list can view this drive.\n\n- Follow us on:\n  - LinkedIn - [#kubestellar](https://www.linkedin.com/feed/hashtag/?keywords=kubestellar)\n  - Medium - [kubestellar.medium.com](https://medium.com/@kubestellar/list/predefined:e785a0675051:READING_LIST)\n\n\n\u003ch2 align=\"left\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/Tarikul-Islam-Anik/Animated-Fluent-Emojis/master/Emojis/Smilies/Red%20Heart.png\" alt=\"Red Heart\" width=\"40\" height=\"40\" /\u003e\n  Contributors\n\u003c/h2\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/kubestellar/ui/graphs/contributors\"\u003e\n    \u003cimg src=\"https://contrib.rocks/image?repo=kubestellar/ui\" alt=\"Contributors\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubestellar%2Fui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkubestellar%2Fui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubestellar%2Fui/lists"}