Setup Guide

Step-by-step guide to set up the Horse Trust platform locally

This guide will walk you through setting up the Horse Trust platform for local development.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js

Version 24.13.0 or higher recommended

Git

Version 2.43.0 or higher

MongoDB

MongoDB Atlas account or local MongoDB instance

npm

Comes with Node.js installation

Project Structure

The Horse Trust platform is a monorepo with two main applications:

S02-26-Equipo-33-Web-App/
├── client/          # Next.js frontend application
├── server/          # Express.js backend application
├── README.md
└── CONTRIBUTING.md

Clone the Repository

First, clone the repository and navigate to the project directory:

git clone [e-mail]:No-Country-simulation/S02-26-Equipo-33-Web-App.git
cd S02-26-Equipo-33-Web-App

Backend Setup (Server)

The backend is built with Express.js and TypeScript, using MongoDB as the database.

1. Navigate to Server Directory

   cd server
   
2. Install Dependencies

   Install all required npm packages:

   npm install
   

   This will install:

   • Express.js - Web framework
   • Mongoose - MongoDB ODM
   • Socket.io - Real-time messaging
   • JWT & bcryptjs - Authentication
   • TypeScript - Type safety
   • And other dependencies
3. Configure Environment Variables

   Copy the example environment file and configure it:

   cp .env.example .env
   

   Edit the .env file with your configuration:

   PORT=8031
   NODE_ENV=development
   MONGO_URI=mongodb+srv://your-username:[e-mail]/horsetrust
   JWT_SECRET=your-secret-key-change-this
   JWT_EXPIRES_IN=10d
   BCRYPT_SALT_ROUNDS=12
   CORS_ORIGINS=*
   

   See the Environment Variables guide for detailed configuration options.

4. Set Up MongoDB Database

   You have two options for MongoDB:

   Option A: MongoDB Atlas (Recommended)

   1. Create a free account at MongoDB Atlas
   2. Create a new cluster
   3. Create a database user with password
   4. Whitelist your IP address (or use 0.0.0.0/0 for development)
   5. Get your connection string and update MONGO_URI in .env

   Option B: Local MongoDB

   # Install MongoDB locally
   # macOS
   brew install mongodb-community
   brew services start mongodb-community
   
   # Ubuntu
   sudo apt-get install mongodb
   sudo systemctl start mongodb
   
   # Use local connection string
   MONGO_URI=mongodb://localhost:27017/horsetrust
   
5. Start Development Server

   Run the server in development mode with hot-reload:

   npm run dev
   

   The server will start on http://localhost:8031 (or your configured PORT).

6. Verify Server is Running

   Test the server endpoint:

   curl http://localhost:8031/test
   

   Expected response:

   {
     "success": true,
     "message": "response Ok!",
     "data": {
       "team": "S02-26-Equipo-33-Web-App",
       "status": "Development"
     }
   }
   

   If you see this response, your backend is configured correctly!

Frontend Setup (Client)

The frontend is built with Next.js 16 and React 19, using TypeScript and Tailwind CSS.

1. Navigate to Client Directory

   Open a new terminal window and navigate to the client directory:

   cd client
   
2. Install Dependencies

   Install all required npm packages:

   npm install
   

   This will install:

   • Next.js 16 - React framework
   • React 19 - UI library
   • Tailwind CSS - Styling
   • Lucide React - Icons
   • TypeScript - Type safety
3. Configure Environment Variables

   Copy the example environment file:

   cp .env.example .env.local
   

   Edit the .env.local file:

   # API URL - Point to your backend server
   NEXT_PUBLIC_API_URL=http://localhost:8031/api
   
   # Cloudinary Configuration
   NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME=di2agiylz
   NEXT_PUBLIC_CLOUDINARY_UPLOAD_PRESET=horse_trust_uploads
   

   Variables prefixed with NEXT_PUBLIC_ are exposed to the browser.

4. Start Development Server

   Run the client in development mode:

   npm run dev
   

   The client will start on http://localhost:8030.

5. Access the Application

   Open your browser and navigate to:

   http://localhost:8030
   

   You should see the Horse Trust application home page!

Running Both Applications

For full functionality, you need to run both the backend and frontend simultaneously:

Terminal 1 (Backend):

cd server
npm run dev
# Server running on http://localhost:8031

Terminal 2 (Frontend):

cd client
npm run dev
# Client running on http://localhost:8030

Available Scripts

Server Scripts

npm run dev    # Start development server with nodemon (hot-reload)
npm run build  # Compile TypeScript to JavaScript
npm start      # Run compiled production server

Client Scripts

npm run dev    # Start Next.js development server (port 8030)
npm run build  # Build optimized production bundle
npm start      # Start production server (port 8030)
npm run lint   # Run ESLint for code quality

Database Connection Details

The server uses Mongoose to connect to MongoDB with the following configuration:

// Connection settings
serverSelectionTimeoutMS: 5000   // Wait 5 seconds for server selection
socketTimeoutMS: 45000            // Socket timeout after 45 seconds

Connection Events:

• connected - Successfully connected to MongoDB
• error - Connection error occurred
• disconnected - Connection lost, automatic reconnection attempts

Real-Time Features (Socket.io)

The platform includes real-time messaging functionality powered by Socket.io:

• Authentication: JWT-based socket authentication
• Events: Message sending, typing indicators, read receipts
• Rooms: User-specific and conversation-specific rooms
• Port: WebSocket runs on the same port as HTTP server (8031)

Troubleshooting

Port Already in Use

If you see EADDRINUSE error:

# Find and kill the process using the port
# macOS/Linux
lsof -ti:8031 | xargs kill -9
lsof -ti:8030 | xargs kill -9

# Windows
netstat -ano | findstr :8031
taskkill /PID <PID> /F

Or change the PORT in your .env file.

MongoDB Connection Failed

Common issues:

1. Invalid connection string - Check your MONGO_URI format
2. IP not whitelisted - Add your IP in MongoDB Atlas Network Access
3. Wrong credentials - Verify username and password
4. Network issues - Check firewall and internet connection

Enable MongoDB connection logs to see detailed error:

# Check server console output for:
# "✔ MongoDB connected: <host>" (success)
# "MongoDB initial connection failed" (failure)

Client Can't Connect to API

Verify:

1. Backend server is running on port 8031
2. NEXT_PUBLIC_API_URL in client .env.local points to correct backend URL
3. CORS is properly configured in server .env
4. Check browser console for network errors

Module Not Found Errors

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# For Next.js cache issues
rm -rf .next
npm run dev

Next Steps

Environment Variables

Learn about all configuration options

Production Deployment

Deploy your application to production

Contributing

Read CONTRIBUTING.md for development guidelines

API Documentation

Explore the API endpoints and usage