SETUP_GUIDE.md

Lin - Comprehensive Setup Guide

This guide provides step-by-step instructions for setting up the Lin application on different operating systems.

📋 Table of Contents

1. Prerequisites
2. Quick Setup
3. Detailed Setup Process
4. Environment Configuration
5. Development Workflow
6. Troubleshooting
7. Platform-Specific Instructions

🚀 Prerequisites

Before you begin, ensure you have the following installed:

System Requirements

• Operating System: Windows 10/11, macOS 10.14+, or Linux (Ubuntu 18.04+)
• RAM: 4GB minimum, 8GB recommended
• Storage: 1GB free space
• Internet Connection: Required for downloading dependencies

Software Requirements

• Node.js: v16.0.0 or higher
• npm: v8.0.0 or higher
• Python: v3.8.0 or higher
• Git: v2.0.0 or higher (for cloning the repository)

Verification Commands

Windows Command Prompt:

# Check Node.js
node --version

# Check npm
npm --version

# Check Python
python --version

# Check Git
git --version

Windows PowerShell:

# Check Node.js
node --version

# Check npm
npm --version

# Check Python
python --version

# Check Git
git --version

Linux/macOS:

# Check Node.js
node --version

# Check npm
npm --version

# Check Python
python3 --version

# Check Git
git --version

🚀 Quick Setup

Option 1: Automated Setup (Recommended)

# Clone the repository
git clone <repository-url>
cd Lin

# Run automated setup
npm run setup

Option 2: Manual Setup

# Clone the repository
git clone <repository-url>
cd Lin

# Install dependencies
npm install

# Setup environment files
npm run setup:env

# Build the project
npm run build

🔧 Detailed Setup Process

Step 1: Clone the Repository

# Clone using HTTPS
git clone https://github.com/your-username/lin.git

# Or clone using SSH
git clone git@github.com:your-username/lin.git

# Navigate to the project directory
cd lin

Step 2: Install Dependencies

# Install root dependencies
npm install

# Install frontend dependencies
npm run install:frontend

# Install backend dependencies
npm run install:backend

Step 3: Configure Environment Variables

Frontend Configuration

# Navigate to frontend directory
cd frontend

# Copy environment template
cp .env.example .env.local

# Edit the environment file
# Open .env.local in your preferred editor

Frontend Environment Variables (.env.local):

# API Configuration
REACT_APP_API_URL=http://localhost:5000
REACT_APP_ENVIRONMENT=development

# Optional: Custom configuration
REACT_APP_APP_NAME=Lin
REACT_APP_APP_VERSION=1.0.0

Backend Configuration

# Navigate to backend directory
cd ../backend

# Copy environment template
cp .env.example .env

# Edit the environment file
# Open .env in your preferred editor

Backend Environment Variables (.env):

# Supabase Configuration
SUPABASE_URL=your_supabase_project_url
SUPABASE_KEY=your_supabase_api_key

# LinkedIn OAuth Configuration
CLIENT_ID=your_linkedin_client_id
CLIENT_SECRET=your_linkedin_client_secret
REDIRECT_URL=http://localhost:5000/api/auth/callback

# AI/ML Configuration
HUGGING_KEY=your_huggingface_api_key

# Security Configuration
JWT_SECRET_KEY=your_jwt_secret_key
SECRET_KEY=your_flask_secret_key

# Application Configuration
DEBUG=True
SCHEDULER_ENABLED=True
PORT=5000

Step 4: Build the Project

# Navigate back to root directory
cd ..

# Build frontend for production
npm run build

Step 5: Verify Installation

# Run tests
npm test

# Check linting
npm run lint

# Verify build
npm run preview

🌐 Environment Configuration

Development Environment

# Start development servers
npm run dev:all

# Or start individually
npm run dev:frontend  # Frontend: http://localhost:3000
npm run dev:backend   # Backend: http://localhost:5000

Production Environment

# Build for production
npm run build:prod

# Start production servers
npm run start:prod

Environment-Specific Configuration

Development

• Frontend runs on http://localhost:3000
• Backend API runs on http://localhost:5000
• Hot reload enabled
• Debug logging enabled

Production

• Frontend built to static files
• Backend runs with optimized settings
• Debug logging disabled
• Error handling optimized

🛠️ Development Workflow

Daily Development

1. Start the Development Environment

   npm run dev:all
   

2. Make Changes to Code

   • Frontend changes are automatically hot-reloaded
   • Backend changes require restart

3. Test Changes

   # Run specific tests
   npm test
   
   # Run linting
   npm run lint
   
   # Fix linting issues
   npm run lint:fix
   

4. Commit Changes

   git add .
   git commit -m "Descriptive commit message"
   git push
   

Building for Production

1. Clean Previous Builds

   npm run clean
   

2. Build for Production

   npm run build:prod
   

3. Test Production Build

   npm run preview
   

4. Deploy

   # Deploy to your preferred hosting platform
   npm run deploy
   

Common Development Tasks

Adding New Dependencies

# Add frontend dependency
cd frontend
npm install package-name

# Add backend dependency
cd ../backend
pip install package-name

Updating Dependencies

# Update frontend dependencies
cd frontend
npm update

# Update backend dependencies
cd ../backend
pip install --upgrade package-name

Database Migrations

# Run database migrations
cd backend
flask db upgrade

🔍 Troubleshooting

Common Issues and Solutions

1. ENOENT Error: no such file or directory

Problem: Running npm commands from the wrong directory Solution: Always run npm commands from the project root directory

# Verify you're in the correct directory
pwd  # Linux/macOS
cd   # Windows (shows current directory)

# List files to confirm package.json exists
ls package.json  # Linux/macOS
dir package.json  # Windows

2. Port Already in Use

Problem: Port 3000 or 5000 is already occupied Solution: Find and stop the process using the port

Windows Command Prompt:

# Find process using port 3000
netstat -ano | findstr :3000

# Find process using port 5000
netstat -ano | findstr :5000

# Kill process (replace PID with actual process ID)
taskkill /F /PID <PID>

Windows PowerShell:

# Find process using port 3000
netstat -ano | Select-String ":3000"

# Find process using port 5000
netstat -ano | Select-String ":5000"

# Kill process (replace PID with actual process ID)
Stop-Process -Id <PID> -Force

Linux/macOS:

# Find process using port 3000
lsof -i :3000

# Find process using port 5000
lsof -i :5000

# Kill process (replace PID with actual process ID)
kill -9 <PID>

3. Python/Node.js Not Recognized

Problem: Command not found errors Solution: Add Python and Node.js to system PATH

Windows:

1. Press Win + R and type sysdm.cpl
2. Go to "Advanced" tab > "Environment Variables"
3. Under "System variables", edit "Path"
4. Add paths to Python and Node.js installation directories
5. Restart your terminal

Linux (Ubuntu/Debian):

# Add to ~/.bashrc or ~/.zshrc
echo 'export PATH=$PATH:/path/to/python' >> ~/.bashrc
echo 'export PATH=$PATH:/path/to/node' >> ~/.bashrc
source ~/.bashrc

macOS:

# Add to ~/.zshrc or ~/.bash_profile
echo 'export PATH=$PATH:/path/to/python' >> ~/.zshrc
echo 'export PATH=$PATH:/path/to/node' >> ~/.zshrc
source ~/.zshrc

4. Permission Denied Errors

Problem: Permission issues when installing dependencies Solution: Run with proper permissions or use package managers

Windows:

# Run as Administrator
# Or check file permissions

Linux/macOS:

# Fix permissions
chmod -R 755 node_modules
chmod -R 755 backend/venv

5. Environment Variable Issues

Problem: Environment variables not loading Solution: Verify file paths and permissions

Windows Command Prompt:

# Check if environment files exist
if exist frontend\.env.local (
    echo Frontend environment file exists
) else (
    echo Frontend environment file missing
)

if exist backend\.env (
    echo Backend environment file exists
) else (
    echo Backend environment file missing
)

Windows PowerShell:

# Check if environment files exist
if (Test-Path frontend\.env.local) {
    Write-Host "Frontend environment file exists" -ForegroundColor Green
} else {
    Write-Host "Frontend environment file missing" -ForegroundColor Red
}

if (Test-Path backend\.env) {
    Write-Host "Backend environment file exists" -ForegroundColor Green
} else {
    Write-Host "Backend environment file missing" -ForegroundColor Red
}

🖥️ Platform-Specific Instructions

Windows Setup

Prerequisites Installation

1. Download Node.js: Visit https://nodejs.org and download the LTS version
2. Download Python: Visit https://python.org and download Python 3.8+
3. Install Git: Download from https://git-scm.com

Environment Setup

# Command Prompt setup
copy frontend\.env.example frontend\.env.local
copy backend\.env.example backend\.env

# PowerShell setup
Copy-Item frontend\.env.example -Destination frontend\.env.local
Copy-Item backend\.env.example -Destination backend\.env

Development Commands

# Install dependencies
npm install
npm run install:all:win

# Start development
npm run dev:all

# Build project
npm run build

macOS Setup

Prerequisites Installation

# Install using Homebrew
brew install node
brew install python
brew install git

# Or download from official websites

Environment Setup

# Copy environment files
cp frontend/.env.example frontend/.env.local
cp backend/.env.example backend/.env

# Set permissions
chmod 600 frontend/.env.local
chmod 600 backend/.env

Development Commands

# Install dependencies
npm install
npm run install:all

# Start development
npm run dev:all

# Build project
npm run build

Linux Setup

Prerequisites Installation

# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm python3 python3-pip git

# CentOS/RHEL
sudo yum install nodejs npm python3 python3-pip git

# Arch Linux
sudo pacman -S nodejs npm python python-pip git

Environment Setup

# Copy environment files
cp frontend/.env.example frontend/.env.local
cp backend/.env.example backend/.env

# Set permissions
chmod 600 frontend/.env.local
chmod 600 backend/.env

Development Commands

# Install dependencies
npm install
npm run install:all

# Start development
npm run dev:all

# Build project
npm run build

📚 Additional Resources

• API Documentation
• Frontend Development Guide
• Windows Compatibility Guide
• Troubleshooting Guide
• Contributing Guidelines

🆘 Getting Help

If you encounter issues not covered in this guide:

1. Check the Troubleshooting Guide
2. Search existing GitHub Issues
3. Create a new issue with:
   • Operating system and version
   • Node.js and Python versions
   • Error messages and stack traces
   • Steps to reproduce the issue

🎯 Next Steps

After completing the setup:

1. Explore the Application: Navigate to http://localhost:3000
2. Read the Documentation: Check the API documentation and user guides
3. Join the Community: Join our Discord server or mailing list
4. Start Contributing: Check out the contributing guidelines

Happy coding! 🚀