Skip to main content

Installation Guide

System Requirements​

OSMinimum Version
Windows10 (1903+)
macOS11 (Big Sur)
LinuxUbuntu 20.04+

Build from Source​

1. Clone the Repository​

git clone https://github.com/chaosys123/opentree.git
cd opentree

2. Install Dependencies​

# Recommended: npm
npm install

# Or use yarn
yarn install

# Or use pnpm (faster)
pnpm install

3. Run in Development Mode​

npm run dev

This will start:

  • Vite dev server (localhost:5173)
  • Electron main process
  • Backend API service

4. Production Build​

# Build production version
npm run build

# Package as executable
npm run package

# Package for current platform only
npm run package:win   # Windows
npm run package:mac   # macOS
npm run package:linux # Linux

Docker​

docker run -d \
  --name opentree \
  -p 3000:3000 \
  -v opentree-data:/app/data \
  ghcr.io/opentree/opentree:latest

Environment Variables​

Create a .env file:

# Database
DB_PATH=./data/opentree.db

# Backend API
API_PORT=3210

# Dev server
DEV_SERVER_PORT=5173

# Metaverse
METAVERSE_PORT=5174

# Feature flags
ENABLE_TELEMETRY=false
ENABLE_AUTO_UPDATE=true

Common Issues​

Node Version Mismatch​

Use nvm to manage Node versions:

nvm install 18
nvm use 18

Slow Electron Download​

Set mirror:

# Windows PowerShell
$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"

# Linux/macOS
export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/

Permission Issues (Linux)​

sudo chown -R $USER ~/.config/opentree