Genie Web Client

An AI-powered, extensible UI framework built on the OpenShift Console dynamic plugin, enabling unified, intelligent experiences across Red Hat products.

Prerequisites

• Node.js 20+ and yarn - For frontend development
• Python 3.12+ (requires >=3.12, <3.14) - For backend (Lightspeed services). See lightspeed-stack requirements
• Go 1.24.6+ - For obs-mcp server. See obs-mcp requirements
• OpenShift CLI (oc) - To connect to a cluster
• Podman 3.2.0+ or Docker - To run the console
• OpenAI API Key - Or compatible LLM provider

Getting Started

Genie Web Client requires both a frontend (this repo) and a backend (AI service). Follow these steps:

1. Setup Backend (One-Time)

The backend provides AI capabilities. See detailed instructions in backend/README.md.

Quick Start:

# First, clone and start obs-mcp server (terminal 1)
# Make sure you're logged into your OpenShift cluster
oc login

# Clone obs-mcp (one time only, skip if you already have it)
cd ~/Documents/GHRepos  # or wherever you keep repos
git clone https://github.com/rhobs/obs-mcp.git
cd obs-mcp

# Start obs-mcp (auto-discovers Prometheus in the cluster)
go run cmd/obs-mcp/main.go --listen 127.0.0.1:9100 --auth-mode kubeconfig --insecure --guardrails none
# Runs on port 9100 - keep running

# Then in another terminal, setup lightspeed-stack
# Clone lightspeed-stack
cd ~/Documents/GHRepos  # or your preferred location
git clone https://github.com/lightspeed-core/lightspeed-stack.git
cd lightspeed-stack

# Copy our configs
cp ~/Documents/GHRepos/genie-web-client/backend/lightspeed-stack/*.yaml .

# Install and start
uv sync
export OPENAI_API_KEY="sk-your-key-here"
uv run python -m src.lightspeed_stack

# Runs on port 8080 - keep this terminal running

2. Setup Frontend

In separate terminal windows, run:

Terminal 3: Plugin Dev Server

cd ~/Documents/GHRepos/genie-web-client
yarn install
yarn run start
# Runs on port 9001 - keep running

Terminal 4: OpenShift Console

cd ~/Documents/GHRepos/genie-web-client
oc login  # Connect to your cluster
yarn run start-console
# Runs on port 9000 - keep running

Access the app: http://localhost:9000/genie

Testing MCP Tool Calls

Once everything is running, you can test obs-mcp integration with these queries:

• "What alerts are firing in the cluster?"
• "Show me CPU usage metrics"
• "What pods are running in the openshift-monitoring namespace?"

Development

Option 1: Local (Recommended)

In one terminal window, run:

1. yarn install
2. yarn run start

In another terminal window, run:

1. oc login (requires oc and an OpenShift cluster)
2. yarn run start-console (requires Docker or podman 3.2.0+)

This will run the OpenShift console in a container connected to the cluster you've logged into. The plugin HTTP server runs on port 9001 with CORS enabled.

Note: Make sure the backend is running (see "Getting Started" section above) for full AI functionality.

Navigate to http://localhost:9000/genie to see the running plugin.

Running start-console with Apple silicon and podman

If you are using podman on a Mac with Apple silicon, yarn run start-console might fail since it runs an amd64 image. You can workaround the problem with qemu-user-static by running these commands:

podman machine ssh
sudo -i
rpm-ostree install qemu-user-static
systemctl reboot

Option 2: Docker + VSCode Remote Container

Make sure the Remote Containers extension is installed. This method uses Docker Compose where one container is the OpenShift console and the second container is the plugin. It requires that you have access to an existing OpenShift cluster. After the initial build, the cached containers will help you start developing in seconds.

1. Create a dev.env file inside the .devcontainer folder with the correct values for your cluster:

OC_PLUGIN_NAME=console-plugin-template
OC_URL=https://api.example.com:6443
OC_USER=kubeadmin
OC_PASS=<password>

2. (Ctrl+Shift+P) => Remote Containers: Open Folder in Container...
3. yarn run start
4. Navigate to http://localhost:9000/genie

Testing

Unit Tests

This project uses Jest and React Testing Library for unit testing.

Running Tests

# Run all tests once
yarn test

# Run tests in watch mode (re-runs on file changes)
yarn test:watch

# Run tests with coverage report
yarn test:coverage

Writing Tests

Tests should be placed alongside the components they test with a .test.tsx extension. For components with multiple test files, use a __tests__/ directory.

File Organization:

• Single test file: src/components/MyComponent.test.tsx (co-located)
• Multiple test files: src/components/my-component/__tests__/ (organized)

Example test:

import { render, screen } from '@testing-library/react';
import MyComponent from './MyComponent';

describe('MyComponent', () => {
  it('renders correctly', () => {
    render(<MyComponent />);
    expect(screen.getByText('Expected Text')).toBeInTheDocument();
  });
});

Integration Tests

Integration tests using Cypress are available. See the integration-tests directory for more details.

# Run Cypress in interactive mode
yarn test-cypress

# Run Cypress in headless mode
yarn test-cypress-headless

Troubleshooting

"No module named 'mcp'" Error

If you get this error when starting lightspeed-stack:

ModuleNotFoundError: No module named 'mcp'

Solution: Install the required dependencies:

cd ~/Documents/GHRepos/lightspeed-stack
uv pip install mcp
# Or install all optional dependencies:
uv pip install pandas psycopg2-binary redis aiosqlite pillow "mcp>=1.23.0" scikit-learn pymongo matplotlib

This happens because uv sync only installs dependencies from pyproject.toml, but llama-stack requires additional packages for MCP support.

Other Issues

For backend-specific troubleshooting (port conflicts, API keys, etc.), see backend/README.md.

Contributing

See CONTRIBUTING.md for guidelines. A PR template is in place (see .github/pull_request_template.md) prompting for a summary and testing details.