Getting Started - Orphelix

Overview

This guide walks you through setting up a complete Orphelix development environment, from initial repository clone to running tests and making your first contribution.

For production deployment, see Deployment Guide.

Prerequisites

Required Software

Node.js 20+

Version: 20.11.0 or laterInstall with nvm (recommended):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node.js 20
nvm install 20
nvm use 20

# Verify
node --version
# v20.11.0 or higher

Alternative (direct install):

macOS: brew install node@20
Windows: Download from nodejs.org
Linux: Use package manager (apt, yum, etc.)

npm 10+ (or pnpm/yarn)

npm comes with Node.js:

npm --version
# 10.0.0 or higher

Or use pnpm (faster):

npm install -g pnpm
pnpm --version

Or use yarn:

npm install -g yarn
yarn --version

Git 2.30+

Verify installation:

git --version
# git version 2.30.0 or higher

Install if needed:

macOS: brew install git
Windows: Download from git-scm.com
Linux: sudo apt install git or sudo yum install git

kubectl 1.25+ (for real cluster testing)

Version: 1.25.0 or laterInstall:

# macOS
brew install kubectl

# Linux
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/

# Windows (PowerShell)
choco install kubernetes-cli

Verify:

kubectl version --client

Note: Not required for demo mode development

Docker (optional - for local Kubernetes cluster)

For running local test cluster:Install Docker Desktop:

macOS/Windows: docker.com/products/docker-desktop
Linux: Follow docs.docker.com

Enable Kubernetes in Docker Desktop:

Open Docker Desktop
Settings → Kubernetes
Check “Enable Kubernetes”
Click “Apply & Restart”

Alternative: Minikube or Kind:

# Minikube
brew install minikube
minikube start

# Kind
brew install kind
kind create cluster

Optional Tools

VS Code - Recommended IDE with extensions:
- TypeScript and JavaScript
- ESLint
- Prettier
- Tailwind CSS IntelliSense
- YAML
GitHub CLI (gh) - Simplifies PR creation
PostgreSQL client (for database inspection)

Repository Setup

1. Clone Repository

# HTTPS
git clone https://github.com/corapoid/orphelix.git

# SSH (recommended)
git clone git@github.com:corapoid/orphelix.git

cd orphelix/app

2. Install Dependencies

npm
pnpm
yarn

npm install

pnpm install

yarn install

This installs:

Next.js 15 and React 19
Material-UI v7
Kubernetes client node
TanStack Query
Vitest and Playwright
…and 50+ other packages

Expected output:

added 1245 packages in 45s

3. Environment Configuration

Create environment file:

cp .env.example .env.local

Edit .env.local:

# Database (SQLite - auto-created)
DATABASE_URL=file:./orphelix.db

# NextAuth (generate with: openssl rand -base64 32)
NEXTAUTH_SECRET=your-secret-here
NEXTAUTH_URL=http://localhost:3000

# GitHub OAuth (optional - for login authentication)
GITHUB_ID=your-oauth-app-client-id
GITHUB_SECRET=your-oauth-app-client-secret

# GitHub App (optional - for GitOps features)
GITHUB_APP_ID=123456
GITHUB_APP_CLIENT_ID=Iv1.abc123
GITHUB_APP_CLIENT_SECRET=secret
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"

# OpenAI (optional - for AI features)
OPENAI_API_KEY=sk-...

# Node environment
NODE_ENV=development

Demo Mode: You can skip GitHub and OpenAI configuration if you only want to work on demo mode features.

4. Database Setup

Initialize SQLite database:

# Database is created automatically on first run
npm run dev

The database file orphelix.db will be created in the app/ directory. Schema location: app/lib/db/schema.sql Inspect database:

sqlite3 orphelix.db

sqlite> .tables
# user_settings  github_settings  cluster_aliases  ...

sqlite> .schema user_settings
# CREATE TABLE user_settings (...);

sqlite> .quit

Development Workflow

Start Development Server

npm
Turbopack (faster)

npm run dev

npm run dev -- --turbopack

Server starts at http://localhost:3000 Features enabled in dev mode:

Hot Module Replacement (HMR)
Fast Refresh (instant updates)
Source maps
Detailed error pages
React Query DevTools
Turbopack compilation (optional)

Console output:

▲ Next.js 15.0.3
- Local:        http://localhost:3000
- Ready in 2.1s

✓ Compiled /

Demo Mode (No Cluster Required)

Default mode - no kubeconfig needed:

Start dev server: npm run dev
Open http://localhost:3000
Click “Switch to Demo Mode” (or it’s already selected)
Explore with mock data:
- 15 deployments
- 42 pods
- 3 nodes
- 25 ConfigMaps/Secrets
- 150+ events

Perfect for:

UI development
Component testing
Learning the codebase
Presentations

Real Cluster Mode

Requires kubeconfig:

Configure kubectl:

# Check current context
kubectl config current-context

# List available contexts
kubectl config get-contexts

# Switch context
kubectl config use-context my-cluster

Verify access:

kubectl get nodes
kubectl get pods --all-namespaces

Start Orphelix:
```
npm run dev
```
Switch to Real mode in UI
Select cluster context
Select namespace

Supported clusters:

AWS EKS
Google GKE
Azure AKS
Minikube
Kind
Docker Desktop Kubernetes
Any Kubernetes 1.25+

Project Structure Quick Tour

app/
├── app/                      # Next.js App Router
│   ├── api/                 # Backend API routes
│   ├── components/          # React components
│   ├── deployments/         # Deployments pages
│   ├── pods/                # Pods pages
│   └── ...                  # Other pages
│
├── lib/                      # Shared libraries
│   ├── hooks/               # React hooks (TanStack Query)
│   ├── k8s/                 # Kubernetes client
│   ├── db/                  # Database (SQLite)
│   ├── github/              # GitHub integration
│   ├── ai/                  # AI features
│   └── mocks/               # Demo mode data
│
├── types/                    # TypeScript types
│   ├── kubernetes.ts        # K8s resource types
│   ├── app.ts               # App types
│   └── topology.ts          # Topology types
│
├── public/                   # Static assets
│   └── logo/                # Logos and icons
│
├── tests/                    # E2E tests (Playwright)
│   └── e2e/
│
├── __tests__/               # Unit tests (Vitest)
│   └── lib/
│
├── package.json             # Dependencies
├── tsconfig.json            # TypeScript config
├── next.config.mjs          # Next.js config
├── vitest.config.ts         # Vitest config
├── playwright.config.ts     # Playwright config
└── orphelix-cli.js          # CLI tool

Running Tests

Unit Tests (Vitest)

Run all tests
Watch mode
Coverage
Specific test

npm test

npm run test:watch

npm run test:coverage

Open coverage/index.html to see report

npm test -- use-deployments.test.ts

Expected output:

✓ lib/utils.test.ts (12)
✓ lib/store.test.ts (8)
✓ lib/hooks/use-deployments.test.ts (6)

Test Files  3 passed (3)
     Tests  26 passed (26)

E2E Tests (Playwright)

Run all E2E tests
Interactive mode
Specific browser
Headed mode

npm run test:e2e

npm run test:e2e:ui

npm run test:e2e -- --project=chromium
npm run test:e2e -- --project=firefox
npm run test:e2e -- --project=webkit

npm run test:e2e -- --headed

Note: E2E tests start dev server automatically

Type Checking

npm run type-check

This runs tsc --noEmit to check TypeScript types without compilation.

Linting

Check
Fix

npm run lint

npm run lint:fix

Format Code

npm run format

Formats all files with Prettier.

Making Changes

1. Create Feature Branch

git checkout -b feature/my-feature
# or
git checkout -b fix/bug-description

Branch naming:

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation
refactor/ - Code refactoring
test/ - Test improvements

2. Make Changes

Example: Add new resource view

Create API route:

// app/api/services/route.ts
export async function GET(request: NextRequest) {
  // Fetch services from Kubernetes
}

Create custom hook:

// lib/hooks/use-services.ts
export function useServices() {
  return useQuery({
    queryKey: ['services'],
    queryFn: async () => {
      const res = await fetch('/api/services')
      return res.json()
    },
  })
}

Create page component:

// app/services/page.tsx
export default function ServicesPage() {
  const { data, isLoading } = useServices()
  return <ServiceList services={data} />
}

Add tests:

// __tests__/lib/hooks/use-services.test.ts
describe('useServices', () => {
  it('fetches services', async () => {
    // Test implementation
  })
})

3. Test Changes

# Type check
npm run type-check

# Lint
npm run lint

# Unit tests
npm test

# E2E tests
npm run test:e2e

# Manual testing
npm run dev

4. Commit Changes

git add .
git commit -m "feat: add services resource view"

Commit message format:

feat: - New feature
fix: - Bug fix
docs: - Documentation
style: - Code style (formatting, etc.)
refactor: - Code refactoring
test: - Tests
chore: - Build, dependencies, etc.

5. Push and Create PR

# Push to your fork
git push origin feature/my-feature

# Create PR (with GitHub CLI)
gh pr create --title "Add services resource view" --body "Implements #123"

Common Development Tasks

Add New Dependency

npm install package-name

# Dev dependency
npm install -D package-name

Update package.json and commit:

git add package.json package-lock.json
git commit -m "chore: add package-name dependency"

Add New API Route

Create route file:

mkdir -p app/api/my-resource
touch app/api/my-resource/route.ts

Implement handler:

import { NextRequest } from 'next/server'

export async function GET(request: NextRequest) {
  // Implementation
  return Response.json({ data: [] })
}

Add tests:

touch __tests__/api/my-resource.test.ts

Add New Component

Create component file:
```
touch app/components/my-component.tsx
```

Implement component:

export function MyComponent({ prop }: Props) {
  return <div>{prop}</div>
}

Export from index (if creating component library):

// app/components/index.ts
export * from './my-component'

Add Demo Mode Data

Edit mock data file:

// lib/mocks/data.ts
export const mockMyResources: MyResource[] = [
  {
    name: 'resource-1',
    // ... mock data
  },
  // Add more mocks
]

Debug Application

VS Code launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    }
  ]
}

Chrome DevTools:

Open chrome://inspect
Click “Open dedicated DevTools for Node”
Start dev server with --inspect

React DevTools:

# Install extension
# Chrome: https://chrome.google.com/webstore/detail/react-developer-tools
# Firefox: https://addons.mozilla.org/en-US/firefox/addon/react-devtools/

Troubleshooting

Port 3000 Already in Use

# Find process using port
lsof -i :3000

# Kill process
kill -9 <PID>

# Or use different port
npm run dev -- -p 3001

Node Modules Issues

# Clean install
rm -rf node_modules package-lock.json
npm install

# Or with cache clear
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

TypeScript Errors

# Restart TypeScript server (VS Code)
# Cmd+Shift+P → "TypeScript: Restart TS Server"

# Check tsconfig
npm run type-check

Database Locked

# Close all connections
pkill -f "node.*next"

# Delete and recreate
rm orphelix.db
npm run dev

kubectl Not Working

# Check config
kubectl config view

# Check current context
kubectl config current-context

# Test connection
kubectl get nodes

# Check permissions
kubectl auth can-i get pods --all-namespaces

Build Fails

# Check Node version
node --version  # Should be 20+

# Clean build cache
rm -rf .next
npm run build

# Check for TypeScript errors
npm run type-check

IDE Setup

VS Code

Recommended extensions:

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "ms-vscode.vscode-typescript-next",
    "redhat.vscode-yaml",
    "ms-kubernetes-tools.vscode-kubernetes-tools"
  ]
}

Settings:

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

WebStorm / IntelliJ

Open project
Enable TypeScript support
Set Node.js interpreter (v20+)
Enable ESLint
Enable Prettier

Next Steps

Architecture

Understand system design

Project Structure

Learn code organization

Testing Guide

Write and run tests

Contributing

Contribution guidelines

Getting Help

Documentation: docs.orphelix.dev
GitHub Issues: github.com/corapoid/orphelix/issues
Discussions: github.com/corapoid/orphelix/discussions

Join our community! We’re here to help you get started and answer any questions.

Developer Guide

Development

API Reference

​Overview

​Prerequisites

​Required Software

​Optional Tools

​Repository Setup

​1. Clone Repository

​2. Install Dependencies

​3. Environment Configuration

​4. Database Setup

​Development Workflow

​Start Development Server

​Demo Mode (No Cluster Required)

​Real Cluster Mode

​Project Structure Quick Tour

​Running Tests

​Unit Tests (Vitest)

​E2E Tests (Playwright)

​Type Checking

​Linting

​Format Code

​Making Changes

​1. Create Feature Branch

​2. Make Changes

​3. Test Changes

​4. Commit Changes

​5. Push and Create PR

​Common Development Tasks

​Add New Dependency

​Add New API Route

​Add New Component

​Add Demo Mode Data

​Debug Application

​Troubleshooting

​Port 3000 Already in Use

​Node Modules Issues

​TypeScript Errors

​Database Locked

​kubectl Not Working

​Build Fails

​IDE Setup

​VS Code

​WebStorm / IntelliJ

​Next Steps

Architecture

Project Structure

Testing Guide

Contributing

​Getting Help

Overview

Prerequisites

Required Software

Optional Tools

Repository Setup

1. Clone Repository

2. Install Dependencies

3. Environment Configuration

4. Database Setup

Development Workflow

Start Development Server

Demo Mode (No Cluster Required)

Real Cluster Mode

Project Structure Quick Tour

Running Tests

Unit Tests (Vitest)

E2E Tests (Playwright)

Type Checking

Linting

Format Code

Making Changes

1. Create Feature Branch

2. Make Changes

3. Test Changes

4. Commit Changes

5. Push and Create PR

Common Development Tasks

Add New Dependency

Add New API Route

Add New Component

Add Demo Mode Data

Debug Application

Troubleshooting

Port 3000 Already in Use

Node Modules Issues

TypeScript Errors

Database Locked

kubectl Not Working

Build Fails

IDE Setup

VS Code

WebStorm / IntelliJ

Next Steps

Getting Help