Mantis Docs

Appearance

Perfect for Mac users who want to run just the frontend and connect to a hosted backend server.

What You're Setting Up ​

  • Frontend Only: Next.js React application running locally
  • Backend: Connects to remote hosted backend server (no local backend setup needed)
  • Perfect for: Frontend developers, designers, or quick demos

Step 1: Install Prerequisites ​

Install Homebrew (if you don't have it) ​

# Check if you have Homebrew

brew --version

# If not installed, install it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Add to your PATH (follow the instructions shown after install)

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc

source ~/.zshrc

Install Node.js and Yarn ​

# Install Node.js (JavaScript runtime)

brew install node

# Install Yarn (package manager)

npm install --global yarn

# Verify installations

node --version    # Should be v18 or higher

yarn --version

Install Git (usually pre-installed) ​

# Check if installed

git --version

# If not installed:

brew install git

# Configure Git

git config --global user.name "Your Name"

git config --global user.email "your.email@example.com"

Step 2: Get the Code ​

# Create a folder for all Mantis projects

mkdir MantisCodebase

cd MantisCodebase

# Clone the frontend repository

git clone https://github.com/KellisLab/Mantis.git

cd Mantis

# Navigate to the frontend folder

cd Mantis

Step 3: Install Dependencies ​

# Install all required packages (this may take a few minutes)

yarn install

# If you get permission errors, try:

sudo yarn install

Step 4: Configure Backend Connection ​

# Create environment (env) file to connect to MIT hosted server

echo 'NEXT_PUBLIC_BACKEND_URL="https://kellis-h200-1.csail.mit.edu"' > .env.local

Step 5: Start the Frontend ​

# Start the development server

yarn dev

What you'll see:

yarn run v1.22.22

$ cross-env NEXTAUTH_URL="http://localhost:3000" next dev

▲ Next.js 15.5.6

- Local:        http://localhost:3000

- Network:      http://192.168.0.22:3000

✓ Ready in 1266ms

Step 6: Open Mantis ​

  1. Open your browser
  2. Go to: http://localhost:3000
  3. You should see: Mantis login/home page

Daily Usage ​

Starting Mantis ​

# Navigate to project folder

cd MantisCodebase/Mantis

# Start the frontend

yarn dev

# Open browser to http://localhost:3000

Stopping Mantis ​

  • Press: Ctrl + C in the terminal
  • Or: Close the terminal window

Understanding What's Happening ​

Frontend Architecture ​

  • Next.js: React framework that builds your app
  • TypeScript: Type-safe JavaScript for better development
  • Tailwind CSS: Utility-first CSS framework for styling
  • Proxy: Routes API calls to the backend server

How It Connects to Backend ​

  1. Your browser → Frontend (localhost:3000)
  2. Frontend → Proxy → Backend Server
  3. Backend processes requests and sends data back
  4. Frontend displays the results

What You Can Do ​

  • View and edit notebooks
  • Create visualizations
  • Manage research spaces
  • Collaborate with others
  • All data is stored on the backend server

Making Changes ​

Hot Reloading ​

  • Any changes you make to the code will automatically appear in your browser
  • No need to restart the server for most changes

Common Files to Edit ​

  • Pages: src/app/ - Main application pages
  • Components: src/components/ - Reusable UI components
  • Styles: src/app/globals.css - Global styles

Advanced Configuration ​

Different Backend Servers ​

# Production server

echo 'NEXT_PUBLIC_BACKEND_URL="https://mantisapi.csail.mit.edu"' > .env.local

# Staging server

echo 'NEXT_PUBLIC_BACKEND_URL="https://mantisapixl.csail.mit.edu"' > .env.local

# GPU cluster

echo 'NEXT_PUBLIC_BACKEND_URL="https://mantiscluster.csail.mit.edu"' > .env.local

Development vs Production ​

# Development (hot reloading, debug info)

yarn dev

# Production build (optimized, faster)

yarn build

yarn start

Getting Help ​

Check Logs ​

  • Browser Console: Press F12 → Console tab
  • Terminal: Look for error messages in the terminal running yarn dev

Common Error Messages ​

  • "Network Error": Backend server is down or URL is wrong
  • "Module not found": Run yarn install again
  • "Port in use": Another app is using port 3000

Resources ​

Summary ​

You now have: ✅ Mantis frontend running locally ✅ Connected to hosted backend ✅ Hot reloading for development ✅ No Docker or complex setup needed

To use Mantis daily:

  1. Open Terminal
  2. cd MantisCodebase/Mantis
  3. yarn dev
  4. Open http://localhost:3000

Perfect for frontend development, testing, and demos!