Skip to main content

​
System Requirements

Node.js

Version 20.0.0 or higher

npm

Version 10 or higher (comes with Node.js)

kubectl

Latest stable version (optional for demo mode)

Git

Any recent version

​
Development Installation

For local development and testing:
1

Clone the repository

git clone https://github.com/corapoid/orphelix.git
cd orphelix/app
2

Install dependencies

npm install
This installs all required packages including Next.js, React, Material-UI, and Kubernetes client libraries.
3

Start development server

npm run dev
The server starts with Turbopack for fast hot-reload development.
4

Access the application

Open http://localhost:3000 in your browser.The application starts in Demo Mode automatically.
Development mode includes hot-reload, detailed error messages, and source maps for debugging.

​
Production Installation

For production deployment:
1

Clone and install

git clone https://github.com/corapoid/orphelix.git
cd orphelix/app
npm install
2

Build the application

npm run build
This creates an optimized production build in the .next directory.
3

Start production server

npm start
The server runs on port 3000 by default.

​
Environment Configuration

Create a .env.local file for production settings: 
# Optional: Custom port
PORT=3000

# Optional: GitHub OAuth (for YAML editor)
GITHUB_CLIENT_ID=your_github_oauth_app_client_id
GITHUB_CLIENT_SECRET=your_github_oauth_app_client_secret
NEXTAUTH_SECRET=your_random_secret_here
NEXTAUTH_URL=http://localhost:3000

# Optional: GitHub App (recommended over OAuth)
GITHUB_APP_ID=your_github_app_id
GITHUB_APP_PRIVATE_KEY=your_github_app_private_key
GITHUB_APP_CLIENT_ID=your_github_app_client_id
GITHUB_APP_CLIENT_SECRET=your_github_app_client_secret

# Optional: OpenAI (for AI-powered file matching)
OPENAI_API_KEY=your_openai_api_key

​
Docker Installation

Run Orphelix in a container:

​
Using Docker

# Build image
docker build -t orphelix .

# Run container
docker run -p 3000:3000 \
  -v ~/.kube:/root/.kube:ro \
  orphelix

​
Using Docker Compose

Create docker-compose.yml: 
version: '3.8'
services:
  orphelix:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ~/.kube:/root/.kube:ro
    environment:
      - NODE_ENV=production
Then run: 
docker-compose up -d
The -v ~/.kube:/root/.kube:ro volume mount gives the container read-only access to your kubeconfig. Only use this if you understand the security implications.

​
Kubernetes Deployment

Deploy Orphelix to your Kubernetes cluster:

​
Create Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: orphelix
  namespace: kube-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: orphelix
  template:
    metadata:
      labels:
        app: orphelix
    spec:
      serviceAccountName: orphelix
      containers:
      - name: orphelix
        image: orphelix:latest
        ports:
        - containerPort: 3000
        env:
        - name: NODE_ENV
          value: "production"

​
Create Service

apiVersion: v1
kind: Service
metadata:
  name: orphelix
  namespace: kube-system
spec:
  selector:
    app: orphelix
  ports:
  - port: 80
    targetPort: 3000
  type: LoadBalancer

​
Create ServiceAccount & RBAC

apiVersion: v1
kind: ServiceAccount
metadata:
  name: orphelix
  namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: orphelix
rules:
- apiGroups: [""]
  resources: ["pods", "nodes", "configmaps", "secrets", "events", "namespaces"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["autoscaling"]
  resources: ["horizontalpodautoscalers"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: orphelix
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: orphelix
subjects:
- kind: ServiceAccount
  name: orphelix
  namespace: kube-system
Apply all manifests: 
kubectl apply -f orphelix-deployment.yaml

​
Verification

After installation, verify everything works:
1

Check the application loads

Navigate to http://localhost:3000
2

Verify demo mode

You should see the “DEMO MODE” badge in the header and sample data on the dashboard
3

Test cluster connection (optional)

Click “DEMO MODE” → Select a kubectl context → Click “Test Connection”

​
Troubleshooting

If port 3000 is occupied:
PORT=3001 npm run dev
Delete node_modules and reinstall:
rm -rf node_modules package-lock.json
npm install
Verify your kubeconfig:
kubectl cluster-info
kubectl get nodes
Clear Next.js cache:
rm -rf .next
npm run build

​
Next Steps

Quickstart Guide

Learn the basics in 5 minutes

Configuration

Configure cluster connection and settings

User Guide

Explore all features

GitHub Integration

Set up GitOps workflow