Skip to main content

​
Installation

​
Prerequisites

Before installing Orphelix, ensure you have:
  • Node.js >= 24.0.0 (Download)
  • kubectl installed and configured (optional, for real cluster access) (Install Guide)
  • Git to clone the repository
  • macOS or Linux operating system

​
Install from Source

Clone and set up Orphelix: 
# Clone the repository
git clone https://github.com/corapoid/orphelix.git
cd orphelix/app
That’s it! The CLI is available via npm run orphelix.

​
First Run

Start Orphelix for the first time: 
npm run orphelix start

​
What Happens on First Run?

The CLI will automatically:
  1. Check Dependencies 
    📦 Checking dependencies...
✅ Node.js version: v24.11.1
  2. Install npm Packages (if needed) 
    📦 Installing dependencies...
[npm install output]
✅ Dependencies installed
  3. Build Standalone App (if needed) 
    🔨 Building standalone application...
[build output]
✅ Build complete
  4. Configure Hostname (interactive) 
    🌐 Configure custom hostname orphelix.local?
   This requires sudo to modify /etc/hosts

   Configure now? [Y/n]: y

[sudo] Password for user:
✅ Hostname configured
  5. Initialize Database 
    💾 Initializing database...
✅ Database initialized at ./orphelix.db
  6. Start Application 
    🚀 Starting Orphelix...
✅ Orphelix is running!
📍 Open in browser: http://orphelix.local:3000
📍 Or: http://localhost:3000

🔔 Notification worker started

📊 View logs: npm run orphelix logs
🛑 Stop: npm run orphelix stop

​
Configuration Options

​
Custom Port

Run on a different port: 
# Via command flag
npm run orphelix start -- --port 8080

# Via environment variable
export ORPHELIX_PORT=8080
npm run orphelix start

​
Skip Hostname Configuration

If you don’t want to configure orphelix.local, answer “No” when prompted: 
Configure custom hostname orphelix.local? [Y/n]: n
⏭️  Skipped hostname configuration
You can still access via http://localhost:3000

​
Verify Everything is Working

After installation, check the status: 
npm run orphelix status
Expected output: 
┌────────────┬────┬──────┬────────┬─────┬─────────┐
│ name       │ id │ mode │ status │ cpu │ memory  │
├────────────┼────┼──────┼────────┼─────┼─────────┤
│ orphelix   │ 0  │ fork │ online │ 0%  │ 150 MB  │
└────────────┴────┴──────┴────────┴─────┴─────────┘
Open in browser: 
npm run orphelix open

​
Directory Structure

After installation, Orphelix creates: 
orphelix/app/
├── orphelix.db              # SQLite database
├── orphelix.db-shm          # Database shared memory
├── orphelix.db-wal          # Database write-ahead log
├── .next/standalone/        # Built application
├── logs/                    # Application logs
└── node_modules/            # Dependencies
Backups are stored in: 
~/orphelix-backups/
├── orphelix-backup-2025-11-26-100000.db
├── orphelix-backup-2025-11-25-150000.db
└── ...

​
Troubleshooting Installation

​
”Node version too old”

Upgrade to Node.js 24 or higher: 
# Using nvm
nvm install 24
nvm use 24

# Or download from nodejs.org

​
“kubectl not found”

Install kubectl (only needed for real cluster access): 
# macOS
brew install kubectl

# Linux (Ubuntu/Debian)
sudo apt-get install kubectl

# Or follow official guide
# https://kubernetes.io/docs/tasks/tools/

​
“Port 3000 already in use”

Use a different port: 
npm run orphelix start -- --port 8080
Or kill the process using port 3000: 
lsof -ti:3000 | xargs kill

​
Database initialization failed

Remove the database and restart: 
npm run orphelix stop
rm orphelix.db*
npm run orphelix start

​
Uninstallation

To remove Orphelix: 
# Stop and remove from PM2
npm run orphelix delete

# Remove the repository
cd ..
rm -rf orphelix

# Remove data (optional)
rm -rf ~/orphelix-backups

​
Next Steps

Start Command

Learn about the start command

Configuration

Configure Orphelix settings

Auto-Startup

Enable auto-startup on boot

Troubleshooting

Common issues and solutions