Skip to content

Latest commit

 

History

History
295 lines (212 loc) · 6.15 KB

development-setup.md

File metadata and controls

295 lines (212 loc) · 6.15 KB

🚀 Development Setup Guide

This guide will help you set up a complete development environment for OpenLN projects.

Prerequisites

Before you begin, ensure you have the following installed on your system:

Required Software

Recommended Tools

  • VS Code with extensions:
    • ES7+ React/Redux/React-Native snippets
    • Prettier - Code formatter
    • ESLint
    • MongoDB for VS Code
  • MongoDB Compass (GUI for MongoDB)
  • Postman or Insomnia (API testing)

📥 Repository Setup

1. Fork and Clone the Repository

# Fork the repository on GitHub first, then clone your fork
git clone https://github.com/YOUR_USERNAME/Openln-Engine.git
cd Openln-Engine

# Add upstream remote
git remote add upstream https://github.com/Openln-git/Openln-Engine.git

2. Install Dependencies

The project has separate client and server components:

# Install server dependencies
cd server
npm install

# Install client dependencies
cd ../client
npm install

🔧 Environment Configuration

Server Environment Setup

  1. Create a .env file in the server directory:
cd server
cp .env.example .env  # If example exists, otherwise create new
  1. Configure your .env file with the following variables:
# Server Configuration
PORT=5000
NODE_ENV=development

# Database
MONGODB_URI=mongodb://localhost:27017/openln-dev

# JWT Configuration
JWT_SECRET=your-super-secret-jwt-key-here
JWT_EXPIRE=7d

# Google AI Configuration
GOOGLE_AI_API_KEY=your-google-ai-api-key

# OAuth Configuration (optional for local dev)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# CORS
CLIENT_URL=http://localhost:5173

Client Environment Setup

  1. Create a .env file in the client directory:
cd client
touch .env
  1. Configure your client .env file:
# API Configuration
VITE_API_URL=http://localhost:5000/api
VITE_SERVER_URL=http://localhost:5000

# Google AI (if using client-side AI features)
VITE_GOOGLE_AI_API_KEY=your-google-ai-api-key

🗄️ Database Setup

Local MongoDB Setup

  1. Start MongoDB service:
# On macOS with Homebrew
brew services start mongodb-community

# On Ubuntu/Debian
sudo systemctl start mongod

# On Windows
# Start MongoDB service from Services or run mongod.exe
  1. Create development database:
# Connect to MongoDB
mongosh

# Create and switch to development database
use openln-dev

# Create a test collection (optional)
db.users.insertOne({test: "data"})
  1. Verify connection:
    • Open MongoDB Compass
    • Connect to mongodb://localhost:27017
    • You should see the openln-dev database

MongoDB Atlas Setup (Alternative)

If you prefer using MongoDB Atlas (cloud):

  1. Create account at MongoDB Atlas
  2. Create a free cluster
  3. Get connection string and update MONGODB_URI in your .env

🏃‍♂️ Running the Development Environment

Option 1: Run Both Services Separately

Terminal 1 - Start the server:

cd server
npm run dev

Server will start on http://localhost:5000

Terminal 2 - Start the client:

cd client
npm run dev

Client will start on http://localhost:5173

Option 2: Run with Process Manager (Recommended)

You can create a simple script to run both services:

Create dev-start.sh in the root directory:

#!/bin/bash
# Start both client and server concurrently

echo "Starting OpenLN Development Environment..."

# Start server in background
cd server && npm run dev &
SERVER_PID=$!

# Start client in background  
cd ../client && npm run dev &
CLIENT_PID=$!

# Function to clean up processes
cleanup() {
    echo "Shutting down..."
    kill $SERVER_PID $CLIENT_PID
    exit
}

# Handle interruption
trap cleanup INT TERM

# Wait for both processes
wait $SERVER_PID $CLIENT_PID

Make it executable and run:

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

🧪 Verify Installation

1. Check Server Health

Open http://localhost:5000/api/health in your browser or run:

curl http://localhost:5000/api/health

2. Check Client Application

Open http://localhost:5173 in your browser

3. Check Database Connection

Look for database connection messages in the server terminal output.

🔍 Development Tools

Linting and Code Quality

# Run ESLint on client code
cd client
npm run lint

# Run ESLint with auto-fix
npm run lint:fix

Building for Production

# Build client for production
cd client
npm run build

# Preview production build
npm run preview

🐛 Common Issues and Solutions

Port Already in Use

# Find and kill process using port 5000
lsof -ti:5000 | xargs kill -9

# Or use a different port in your .env file

MongoDB Connection Issues

  • Ensure MongoDB service is running
  • Check connection string in .env
  • Verify network connectivity for Atlas

Node Version Issues

# Check Node version
node --version

# Use Node Version Manager if needed
nvm install 18
nvm use 18

Permission Issues (macOS/Linux)

# Fix npm permissions
sudo chown -R $(whoami) ~/.npm

📚 Next Steps

Once your development environment is set up:

  1. Read the Architecture Overview
  2. Check out the Contributing Guidelines
  3. Explore the API Reference
  4. Look for good first issues

💡 Pro Tips

  • Use npm run dev for hot-reloading during development
  • Install the React Developer Tools browser extension
  • Use MongoDB Compass for database visualization
  • Set up GitHub CLI for easier contribution workflow
  • Configure your IDE with ESLint and Prettier for consistent code formatting

Need help? Open an issue or start a discussion!