Skip to main content

Port Configuration

STEMBlock.ai Port Assignments​

Development Ports​

ServicePortURL
Backend API3001http://localhost:3001
Frontend3000http://localhost:3000
PostgreSQL5432localhost:5432
Prisma Studio5555http://localhost:5555

Starting Services​

Backend (Port 3001):

cd ~/stemblock/backend
npm run start:dev

Verify:

curl http://localhost:3001/health
# Should return: {"status":"ok"}

Frontend (Port 3000):

cd ~/stemblock/frontend
npm run dev

Verify:

Prisma Studio (Port 5555):

cd ~/stemblock/backend
npm run prisma:studio

Verify:

Port Conflicts​

Issue: Port Already in Use​

If you see an error like:

Error: listen EADDRINUSE: address already in use :::3001

Solution 1: Kill the process

# Kill process on port 3001 (backend)
lsof -ti:3001 | xargs kill -9

# Kill process on port 3000 (frontend)
lsof -ti:3000 | xargs kill -9

Solution 2: Find and stop the process

# Find what's using the port
lsof -i:3001

# Output will show:
# COMMAND   PID   USER
# node    12345  maryang
#
# Kill by PID:
kill -9 12345

Solution 3: Use different ports

Backend (.env):

PORT=3002  # Changed from 3001

Frontend (package.json):

{
  "scripts": {
    "dev": "next dev -p 3001"  // Changed from 3000
  }
}

Don't forget to update NEXT_PUBLIC_API_URL in frontend!

Checking Ports​

See all services running​

# macOS/Linux
lsof -i :3000,3001,5432,5555

# Alternative (netstat)
netstat -an | grep -E "3000|3001|5432|5555"

Check specific port​

# Check if port 3001 is in use
lsof -i:3001

# Empty output = port is free
# Output with process info = port is busy

Production Ports​

In production, use:

  • Backend: Port 80 or 443 (with reverse proxy)
  • Frontend: Port 80 or 443 (with reverse proxy)
  • Database: Port 5432 (not publicly exposed)

Example with nginx:

# Frontend
server {
    listen 80;
    server_name stemblock.ai;
    location / {
        proxy_pass http://localhost:3000;
    }
}

# Backend API
server {
    listen 80;
    server_name api.stemblock.ai;
    location / {
        proxy_pass http://localhost:3001;
    }
}

Quick Start Script​

Save this as start-dev.sh:

#!/bin/bash

echo "🚀 Starting STEMBlock.ai Development Environment"
echo ""

# Kill existing processes
echo "🔄 Cleaning up existing processes..."
lsof -ti:3000,3001 | xargs kill -9 2>/dev/null

# Start backend
echo "🔧 Starting backend on port 3001..."
cd ~/stemblock/backend
npm run start:dev &
BACKEND_PID=$!

# Wait for backend to start
sleep 5

# Start frontend
echo "🎨 Starting frontend on port 3000..."
cd ~/stemblock/frontend
npm run dev &
FRONTEND_PID=$!

echo ""
echo "✅ Services started!"
echo "   Backend:  http://localhost:3001 (PID: $BACKEND_PID)"
echo "   Frontend: http://localhost:3000 (PID: $FRONTEND_PID)"
echo ""
echo "Press Ctrl+C to stop all services"

# Wait for interrupt
wait

Make it executable:

chmod +x start-dev.sh
./start-dev.sh

Troubleshooting Common Issues​

Backend starts on wrong port​

Check .env file:

# backend/.env should have:
PORT=3001

Override with environment variable:

PORT=3001 npm run start:dev

Frontend starts on wrong port​

Check package.json:

{
  "scripts": {
    "dev": "next dev -p 3000"  // Port explicitly set
  }
}

Override with npm:

npm run dev -- -p 3000

Can't connect frontend to backend​

1. Check backend is running:

curl http://localhost:3001/health

2. Check frontend environment:

# frontend/.env.local should have:
NEXT_PUBLIC_API_URL=http://localhost:3001

3. Restart both services

4. Check browser console for CORS errors

Last Updated: 2025-11-02