🚀 SparkLumina - Quick Start Guide

Get started with SparkLumina in 5 minutes!

---

📋 General Prerequisites

• ✅ Node.js 18+ (Download)
• ✅ npm (included with Node.js)

Verify versions:

node -v   # v18.0.0 or higher required
npm -v    # 9.0.0 or higher required

---

1️⃣ Local Quick Start via ./start.sh

Dependencies

AI service Python dependencies (first time using AI features):

pip3 install -r backend/src/ai_agent_service/requirements.txt

MP4 transcoding (recording/export video):

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Or specify custom path via .env
# FFMPEG_PATH=/usr/local/bin/ffmpeg

If not installed, the backend will try node_modules/ffmpeg-static; if still unavailable, saving as MP4 will fail.

Startup

# 1. Enter project directory
cd /path/to/SparkLumina

# 2. One-click start (auto-install deps, start frontend + backend + AI service)
./start.sh

The script will automatically:

1. Check Node.js version
2. Install npm dependencies (root, frontend, backend)
3. Start AI Agent service (port 8652)
4. Start frontend (8051) and backend (8056)

Access URL: http://localhost:8051

Optional flags:

• ./start.sh --no-install: Skip dependency install for faster restarts
• Env vars: FRONTEND_HOST, FRONTEND_PORT, BACKEND_HOST, BACKEND_PORT, AI_PORT for custom addresses

---

2️⃣ App Deployment

./release.sh is SparkLumina's unified release entry, supporting desktop installers (Electron) and Android APK.

Dependencies

Environment variables (.env):

cp .env.example .env

Startup

Electron Desktop:

./release.sh mac                 # macOS DMG
./release.sh windows             # Windows exe
./release.sh desktop             # Both DMG + exe on macOS

Android APK:

1. JDK 17 (macOS):

brew install openjdk@17
export JAVA_HOME="$(brew --prefix openjdk@17)"

2. Android SDK: Install Android Studio or brew install --cask android-commandlinetools, set ANDROID_HOME and install platforms;android-36, build-tools;36.0.0.

3. Build:

./release.sh android

Output: app/release/SparkLumina-{version}-android.apk.

release.sh quick reference:

---

3️⃣ Docker Deployment

Dependencies

Prepare .env:

cp .env.example .env

Startup

Image build (push to ACR):

./release.sh docker              # Build and push
./release.sh docker --no-push    # Local build only
./release.sh docker --platform arm64
./release.sh docker --platform both   # Multi-arch

Image list:

• {ACR_REGISTRY}/{ACR_NAMESPACE}/frontend_server:{IMAGE_TAG}
• {ACR_REGISTRY}/{ACR_NAMESPACE}/backend_server:{IMAGE_TAG}
• {ACR_REGISTRY}/{ACR_NAMESPACE}/ai_agent_server:{IMAGE_TAG}

Deploy on server with Docker Compose:

1. Prepare deploy dir: Put docker-compose.yml and .env in the same directory (e.g. /deploy/).

2. Configure .env: Ensure ACR_REGISTRY, ACR_NAMESPACE, IMAGE_TAG match the build.

3. Pull and start:

cd /deploy
docker compose pull
docker compose up -d
docker compose ps

Port mapping:

Visit http://<server-IP>:8051 to use.

---