# Momentry Studio v0.1.0 - Installation Guide

**Release Date**: 2026-10-11  
**Version**: 0.1.0  
**Target**: Admin Team

---

## 📋 Table of Contents

1. [System Requirements](#system-requirements)
2. [Prerequisites](#prerequisites)
3. [Installation Steps](#installation-steps)
4. [Configuration](#configuration)
5. [Building](#building)
6. [Deployment](#deployment)
7. [Verification](#verification)
8. [Troubleshooting](#troubleshooting)
9. [Support](#support)

---

## 🖥️ System Requirements

### Hardware

| Component | Minimum | Recommended |
|-----------|---------|-------------|
| **CPU** | 4 cores | 8 cores (Apple Silicon M1/M2/M3) |
| **RAM** | 8 GB | 16 GB |
| **Storage** | 10 GB | 50 GB |
| **GPU** | - | Apple Silicon GPU or NVIDIA GPU |

### Operating System

- **macOS**: 12.0 (Monterey) or later
- **Architecture**: Apple Silicon (arm64) or Intel (x86_64)

### Network

- **Ports Required**:
  - 3002: Momentry Core API
  - 5173: Vite Dev Server (development only)
  - 8888: Studio Proxy
  - 11438: MarkBase API
  - 6333: Qdrant
  - 6379: Redis (optional)

---

## ✅ Prerequisites

### 1. Node.js and npm

**Minimum Version**: Node.js 18+ and npm 9+

```bash
# Check Node.js version
node --version
# Expected: v18.x.x or higher

# Check npm version
npm --version
# Expected: 9.x.x or higher

# Install Node.js (if not installed)
# Option 1: Using Homebrew
brew install node

# Option 2: Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18
```

---

### 2. Rust and Cargo

**Minimum Version**: Rust 1.70+

```bash
# Check Rust version
rustc --version
# Expected: rustc 1.70.0 or higher

# Check Cargo version
cargo --version
# Expected: cargo 1.70.0 or higher

# Install Rust (if not installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Add to PATH (restart terminal)
source $HOME/.cargo/env
```

---

### 3. PostgreSQL

**Minimum Version**: PostgreSQL 14+

```bash
# Check PostgreSQL version
psql --version
# Expected: psql (PostgreSQL) 14.x or higher

# Install PostgreSQL (if not installed)
brew install postgresql@14

# Start PostgreSQL service
brew services start postgresql@14

# Create database
createdb momentry

# Verify connection
psql -d momentry -c "SELECT version();"
```

---

### 4. Qdrant

**Minimum Version**: Qdrant 1.6+

```bash
# Install Qdrant (if not installed)
brew install qdrant

# Or use Docker
docker run -p 6333:6333 qdrant/qdrant:latest

# Verify Qdrant is running
curl http://localhost:6333/collections
# Expected: {"result": {...}}
```

---

### 5. Redis (Optional)

**Minimum Version**: Redis 7+

```bash
# Install Redis (if not installed)
brew install redis

# Start Redis service
brew services start redis

# Verify Redis is running
redis-cli ping
# Expected: PONG
```

---

### 6. Momentry Core API

**Required**: Momentry Core API must be running on port 3002

```bash
# Verify Core API is running
curl http://localhost:3002/health
# Expected: {"status": "ok", "version": "1.0.0"}
```

**Installation Guide**: See `/Users/accusys/momentry_core/README.md`

---

### 7. MarkBase API

**Required**: MarkBase API must be running on port 11438

```bash
# Verify MarkBase API is running
curl http://localhost:11438/health
# Expected: {"status": "ok"}
```

**Installation Guide**: See `/Users/accusys/markbase/markbase-core/README.md`

---

## 📥 Installation Steps

### Step 1: Clone Repository

```bash
# Clone Momentry Studio
git clone https://github.com/anomalyco/momentry_studio.git
cd momentry_studio

# Or use internal Git server
git clone http://localhost:3000/admin/momentry_studio.git
cd momentry_studio
```

---

### Step 2: Checkout Release Version

```bash
# Checkout v0.1.0
git checkout v0.1.0

# Or use latest main branch
git checkout main
git pull origin main
```

---

### Step 3: Install Dependencies

```bash
# Install Node.js dependencies
npm install

# Expected output:
# added 320 packages in 15s
```

---

### Step 4: Build Frontend

```bash
# Build Vue frontend
npm run build

# Expected output:
# ✓ 87 modules transformed.
# dist/index.html                   0.44 kB
# dist/assets/index-*.css         219 kB
# dist/assets/index-*.js          596 kB
# ✓ built in 911ms
```

---

### Step 5: Build Tauri Desktop App

```bash
# Build Rust proxy (required for both dev and production)
cd src-tauri
cargo build --release
cd ..

# Expected output:
# Compiling momentry-proxy v0.1.0
# Finished release [optimized] target(s) in 2m 15s

# Build Tauri desktop app (optional, for native app)
cargo tauri build

# Expected output:
# Finished release [optimized] target(s) in 5m 30s
# Built: src-tauri/target/release/bundle/dmg/momentry-studio_0.1.0_arm64.dmg
```

---

## ⚙️ Configuration

### 1. Environment Variables

**File**: `.env` (create if not exists)

```env
# Momentry Core API
MOMENTRY_API_URL=http://localhost:3002
MOMENTRY_API_KEY=muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69

# MarkBase API
MARKBASE_API_URL=http://localhost:11438

# Studio Proxy
STUDIO_PROXY_PORT=8888

# Database
DATABASE_URL=postgres://accusys@localhost:5432/momentry

# Qdrant
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=Test3200Test3200Test3200

# Redis (optional)
REDIS_URL=redis://localhost:6379

# VLM Server
MOMENTRY_LLM_VISION_URL=http://localhost:8080/v1/chat/completions

# Data Directory
MOMENTRY_DATA_DIR=/Users/accusys/momentry_studio/data/users
```

---

### 2. Tauri Configuration

**File**: `src-tauri/tauri.conf.json`

**Key Settings**:

```json
{
  "version": "0.1.0",
  "identifier": "com.momentry.studio",
  "build": {
    "beforeBuildCommand": "npm run build",
    "beforeDevCommand": "npm run dev",
    "devUrl": "http://localhost:5173",
    "frontendDist": "../dist"
  },
  "app": {
    "withGlobalTauri": true,
    "windows": [
      {
        "title": "Momentry Studio",
        "width": 1400,
        "height": 900,
        "resizable": true,
        "fullscreen": false
      }
    ]
  }
}
```

---

### 3. Database Setup

**SQLite Database Location**: `data/users/demo.sqlite`

```bash
# Create data directory
mkdir -p data/users

# Database will be created automatically on first run
# Tables: search_history, bookmarks, app_users
```

---

### 4. Proxy Configuration

**File**: `src-tauri/src/proxy.rs`

**Key Settings**:

```rust
// Core API endpoint
const CORE_API: &str = "http://localhost:3002";

// MarkBase API endpoint
const MARKBASE_API: &str = "http://localhost:11438";

// Proxy listen address
let addr = SocketAddr::from(([0, 0, 0, 0], 8888));
```

---

## 🏗️ Building

### Development Build

```bash
# Start development server
npm run dev

# This will:
# 1. Kill old proxy on port 8888
# 2. Start momentry-proxy
# 3. Wait 2 seconds
# 4. Start Vite dev server on port 5173

# Access: http://localhost:5173
```

---

### Production Build

#### Option 1: Web Application

```bash
# Build frontend only
npm run build

# Start proxy manually
npm run proxy

# Access: http://localhost:8888
```

---

#### Option 2: Native Desktop App

```bash
# Build complete desktop app
cargo tauri build

# Output location:
# src-tauri/target/release/bundle/dmg/momentry-studio_0.1.0_arm64.dmg

# Install DMG on macOS
open src-tauri/target/release/bundle/dmg/momentry-studio_0.1.0_arm64.dmg
```

---

## 🚀 Deployment

### Production Deployment (m5max48)

**Target Server**: m5max48

**Deployment Script**:

```bash
#!/bin/bash

# Stop existing services
pkill -f "momentry-proxy"
pkill -f "vite"

# Pull latest code
cd /Users/accusys/momentry_studio
git pull origin main

# Install dependencies
npm install

# Build frontend
npm run build

# Start proxy
MOMENTRY_API_KEY=muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69 \
MOMENTRY_DATA_DIR=$(pwd)/data/users \
./src-tauri/target/release/momentry-proxy > logs/proxy.log 2>&1 &

# Verify
curl http://localhost:8888/health

# Access: https://studio.momentry.ddns.net
```

---

### Systemd Service (Linux)

**File**: `/etc/systemd/system/momentry-studio.service`

```ini
[Unit]
Description=Momentry Studio Proxy
After=network.target postgresql.service

[Service]
Type=simple
User=accusys
WorkingDirectory=/Users/accusys/momentry_studio
Environment="MOMENTRY_API_KEY=muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
Environment="MOMENTRY_DATA_DIR=/Users/accusys/momentry_studio/data/users"
ExecStart=/Users/accusys/momentry_studio/src-tauri/target/release/momentry-proxy
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target
```

```bash
# Enable and start service
sudo systemctl enable momentry-studio
sudo systemctl start momentry-studio
sudo systemctl status momentry-studio
```

---

### Nginx Reverse Proxy

**File**: `/etc/nginx/sites-available/momentry-studio.conf`

```nginx
server {
    listen 443 ssl http2;
    server_name studio.momentry.ddns.net;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8888;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # WebSocket support
    location /ws {
        proxy_pass http://localhost:8888;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
    }
}
```

```bash
# Enable site
sudo ln -s /etc/nginx/sites-available/momentry-studio.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

---

## ✅ Verification

### 1. Check Services

```bash
# Check proxy
curl http://localhost:8888/health
# Expected: ok

# Check Core API
curl http://localhost:3002/health
# Expected: {"status": "ok"}

# Check MarkBase API
curl http://localhost:11438/health
# Expected: {"status": "ok"}
```

---

### 2. Check Frontend

```bash
# Build frontend
npm run build

# Verify build output
ls -lh dist/

# Expected:
# index.html
# assets/index-*.css
# assets/index-*.js
```

---

### 3. Check API Integration

```bash
# Test search API
curl -X POST http://localhost:8888/api/v1/search/keyword \
  -H "Content-Type: application/json" \
  -d '{"query": "test", "limit": 5}'

# Expected: {"success": true, "results": [...]}
```

---

### 4. Check Database

```bash
# Check SQLite database
sqlite3 data/users/demo.sqlite "SELECT * FROM search_history LIMIT 5;"

# Check PostgreSQL
psql -d momentry -c "SELECT COUNT(*) FROM videos;"
```

---

### 5. Check Desktop App (Optional)

```bash
# Run Tauri app in dev mode
cargo tauri dev

# Or install DMG and run
open src-tauri/target/release/bundle/dmg/momentry-studio_0.1.0_arm64.dmg
```

---

## 🔧 Troubleshooting

### Issue 1: Port 8888 Already in Use

**Symptom**: `Address already in use`

**Solution**:

```bash
# Find process using port 8888
lsof -i :8888

# Kill process
kill -9 <PID>

# Or use the provided script
npm run proxy
```

---

### Issue 2: Build Fails with TypeScript Errors

**Symptom**: `error TS2345: Argument of type ...`

**Solution**:

```bash
# Check TypeScript version
npm list typescript

# Update TypeScript
npm install typescript@latest --save-dev

# Rebuild
npm run build
```

---

### Issue 3: Rust Build Fails

**Symptom**: `error: linking with cc failed`

**Solution**:

```bash
# Install Xcode Command Line Tools
xcode-select --install

# Update Rust
rustup update

# Clean and rebuild
cd src-tauri
cargo clean
cargo build --release
```

---

### Issue 4: Database Connection Failed

**Symptom**: `Error: Connection refused`

**Solution**:

```bash
# Check PostgreSQL is running
brew services list | grep postgresql

# Start PostgreSQL
brew services start postgresql@14

# Check database exists
psql -l | grep momentry

# Create database if not exists
createdb momentry
```

---

### Issue 5: API Key Invalid

**Symptom**: `401 Unauthorized`

**Solution**:

```bash
# Check API key in .env file
cat .env | grep MOMENTRY_API_KEY

# Verify API key with Core API
curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:3002/api/v1/search/keyword

# Update API key if needed
# Get new key from Momentry Core admin panel
```

---

### Issue 6: Search Returns No Results

**Symptom**: `{"success": true, "results": []}`

**Solution**:

```bash
# Check Core API has data
curl http://localhost:3002/api/v1/files

# Check PostgreSQL has videos
psql -d momentry -c "SELECT COUNT(*) FROM videos;"

# Check Qdrant has vectors
curl http://localhost:6333/collections/sentence_chunks

# Run file registration if needed
curl -X POST http://localhost:3002/api/v1/files/register \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/path/to/video.mp4"}'
```

---

## 📞 Support

### Documentation

- **Architecture**: `docs/ARCHITECTURE.md`
- **API Reference**: `docs_v1.0/GUIDES/API_REFERENCE.md`
- **Agent Guide**: `AGENTS.md`
- **Changelog**: `CHANGELOG.md`

---

### Contact

- **Development Team**: Momentry Studio Team
- **Issues**: https://github.com/anomalyco/momentry_studio/issues
- **Internal Git**: http://localhost:3000/admin/momentry_studio

---

### Logs

```bash
# Proxy logs
tail -f /tmp/momentry_proxy.log

# Vite logs
tail -f logs/studio.log

# Tauri logs
tail -f ~/Library/Logs/com.momentry.studio/
```

---

## 📦 Release Checklist

- [ ] All prerequisites installed
- [ ] Momentry Core API running (port 3002)
- [ ] MarkBase API running (port 11438)
- [ ] PostgreSQL running (port 5432)
- [ ] Qdrant running (port 6333)
- [ ] Redis running (port 6379) - optional
- [ ] Dependencies installed (`npm install`)
- [ ] Frontend built (`npm run build`)
- [ ] Proxy built (`cargo build --release`)
- [ ] Desktop app built (optional: `cargo tauri build`)
- [ ] Configuration verified (`.env`, `tauri.conf.json`)
- [ ] Database created (`data/users/demo.sqlite`)
- [ ] Health checks passed
- [ ] Search API tested
- [ ] Production deployment verified

---

**Installation Guide Version**: 1.0.0  
**Last Updated**: 2026-10-11  
**Maintained by**: Momentry Studio Team