Skip to content

installation.md

Latest commit

 

History

History
300 lines (200 loc) · 5.34 KB

installation.md

File metadata and controls

300 lines (200 loc) · 5.34 KB
Raw

Installation Guide

Complete installation instructions for MetaHuman Engine.

System Requirements

Minimum Requirements

Component Specification
OS Windows 10+, macOS 11+, or Linux (Ubuntu 20.04+)
RAM 4 GB
Disk 2 GB free space
Browser Chrome 90+, Edge 90+, Firefox 90+, Safari 15+

Recommended Requirements

Component Specification
RAM 8 GB
GPU WebGL 2.0 compatible (for optimal 3D performance)
Network Broadband (for streaming responses)

Frontend Installation

Step 1: Install Node.js 22

macOS (Homebrew):

brew install node@22

Ubuntu/Debian:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

Windows: Download from nodejs.org (LTS version)

Verify installation:

node --version  # Should show v22.x.x
npm --version   # Should show 10.x.x or higher

Step 2: Clone and Setup

# Clone the repository
git clone https://github.com/LessUp/meta-human.git
cd meta-human

# Install dependencies
npm install

# Verify installation
npm run typecheck

Step 3: Configure Environment

Create .env.local:

# Backend API URL (optional - uses mock if not set)
VITE_API_BASE_URL=http://localhost:8000

# Transport mode: http, sse, auto
VITE_CHAT_TRANSPORT=auto

Step 4: Start Development

npm run dev

Access at http://localhost:5173

Optional Backend Example

Option 1: Local Python Environment

Step 1: Install Python 3.10+

macOS:

brew install python@3.10

Ubuntu:

sudo apt-get update
sudo apt-get install python3.10 python3.10-venv

Windows: Download from python.org

Verify:

python --version  # Should show 3.10.x or higher

Step 2: Setup Virtual Environment

cd examples/backend-python

# Create virtual environment
python -m venv venv

# Activate
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

Step 3: Configure Environment

Create examples/backend-python/.env:

cp .env.example .env

# Required for AI responses (optional - mock mode works without)
OPENAI_API_KEY=sk-your-api-key-here

# Optional: Custom endpoint
OPENAI_BASE_URL=https://api.openai.com/v1

# Optional: Model selection
OPENAI_MODEL=gpt-3.5-turbo

# Rate limiting (requests per minute)
RATE_LIMIT_RPM=60

# CORS origins (comma-separated)
CORS_ALLOW_ORIGINS=http://localhost:5173,https://yourdomain.com

Step 4: Start Backend

uvicorn app.main:app --reload --port 8000

Backend runs at http://localhost:8000

API docs at http://localhost:8000/docs

This repository no longer ships Docker, docker-compose, or Render deployment manifests. Treat examples/backend-python/ as a reference implementation and deploy it on your own Python platform if you need a backend.

Deployment

Frontend: GitHub Pages

Step 1: Build

npm run build:pages

Step 2: Configure Repository

  1. Go to GitHub repository → Settings → Pages
  2. Set source to "GitHub Actions"

Step 3: Set Environment Variables

Go to Settings → Secrets and variables → Actions:

Variable Value
VITE_API_BASE_URL Your backend URL

Step 4: Deploy

git push origin master

Or trigger "Deploy Pages" workflow manually.

Optional Backend Example

Deploy examples/backend-python/ to any Python host you control, then point the frontend at it with:

VITE_API_BASE_URL=https://your-backend.example.com

Verification

Frontend Health Check

# Should return the Vite dev server page
curl http://localhost:5173

Backend Health Check

# Should return JSON status
curl http://localhost:8000/health

# Expected response:
# {
#   "status": "ok",
#   "services": {
#     "chat": "available",
#     "llm": "mock_mode",
#     "tts": "available",
#     "asr": "unavailable"
#   }
# }

API Test

# Test chat endpoint
curl -X POST http://localhost:8000/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"userText": "Hello"}'

Troubleshooting

npm install fails

Clear cache and retry:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Python packages fail to install

Upgrade pip:

pip install --upgrade pip setuptools
pip install -r requirements.txt

Port conflicts

Frontend (port 5173):

# Find process
lsof -ti:5173

# Kill process
lsof -ti:5173 | xargs kill -9

Backend (port 8000):

lsof -ti:8000 | xargs kill -9

CORS errors

  1. Verify CORS_ALLOW_ORIGINS includes frontend URL
  2. Ensure no trailing slash mismatches
  3. Check protocol (http vs https)

Next: Configuration →