🚀 Getting Started

This guide will walk you through setting up your development environment for the LIPAIX project. Whether you're new to web development or an experienced developer, we'll cover everything you need to get up and running.

📋 Prerequisites

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

Required Software

Node.js 18+ - JavaScript runtime environment
pnpm - Package manager (faster alternative to npm)
Git - Version control system
Code Editor - VS Code recommended with extensions

System Requirements

Operating System: Windows 10+, macOS 10.15+, or Linux
RAM: Minimum 8GB, recommended 16GB+
Storage: At least 5GB free space
Network: Stable internet connection for package downloads

🔧 Installation Steps

Step 1: Install Node.js

Windows:

Visit nodejs.org
Download the LTS version (18.x or higher)
Run the installer and follow the prompts
Verify installation: node --version

macOS:

bash

# Using Homebrew (recommended)
brew install node

# Or download from nodejs.org
# Verify installation
node --version
npm --version

Linux (Ubuntu/Debian):

bash

# Using NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version
npm --version

Step 2: Install pnpm

pnpm is our preferred package manager because it's faster and more efficient than npm, especially for monorepos.

bash

# Install pnpm globally
npm install -g pnpm

# Verify installation
pnpm --version

Alternative installation methods:

bash

# Using Homebrew (macOS)
brew install pnpm

# Using Curl (Linux/macOS)
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Using PowerShell (Windows)
iwr https://get.pnpm.io/install.ps1 -useb | iex

Step 3: Install Git

Windows:

Download from git-scm.com
Run installer with default settings
Verify: git --version

macOS:

bash

# Git comes pre-installed on macOS
# If not, install with Homebrew:
brew install git

# Verify installation
git --version

Linux:

bash

# Ubuntu/Debian
sudo apt-get install git

# CentOS/RHEL
sudo yum install git

# Verify installation
git --version

Step 4: Install VS Code (Recommended)

VS Code is the recommended editor for this project due to its excellent TypeScript and React support.

Download from code.visualstudio.com
Install with default settings
Install recommended extensions:
- TypeScript Importer - Auto-import TypeScript modules
- ES7+ React/Redux/React-Native snippets - React code snippets
- Tailwind CSS IntelliSense - TailwindCSS autocomplete
- GitLens - Enhanced Git integration
- Prettier - Code formatting
- ESLint - Code linting

🏗️ Project Setup

Step 1: Clone the Repository

bash

# Clone the repository
git clone https://github.com/your-org/lipaix-web-v3.git

# Navigate to the project directory
cd lipaix-web-v3

# Verify you're in the right place
ls -la

You should see a structure like this:

lipaix-web-v3/
├── apps/
├── shared/
├── docs/
├── package.json
├── pnpm-workspace.yaml
└── README.md

Step 2: Install Dependencies

bash

# Install all dependencies for the entire monorepo
pnpm install

# This will install dependencies for:
# - apps/web (Next.js + PayloadCMS)
# - apps/discord-bot (Discord bot)
# - shared/common (shared utilities)
# - docs/vitepress (documentation)

What happens during installation:

pnpm creates a node_modules folder in the root
Dependencies are installed for all packages
Workspace links are created between packages
TypeScript types are generated

Troubleshooting installation issues:

bash

# Clear pnpm cache if you encounter issues
pnpm store prune

# Remove node_modules and reinstall
rm -rf node_modules
pnpm install

# Check for version conflicts
pnpm list --depth=0

Step 3: Environment Configuration

The project requires environment variables to function properly. Let's set these up:

Create environment files:

bash

# Copy the example environment file
cp .env.example .env.local

# Or create a new one
touch .env.local

Required environment variables:

bash

# Database
DATABASE_URI=postgresql://username:password@localhost:5432/lipaix

# PayloadCMS
PAYLOAD_SECRET=your-secret-key-here
PAYLOAD_PUBLIC_SERVER_URL=http://localhost:3000

# Discord Bot
DISCORD_TOKEN=your-discord-bot-token
DISCORD_CLIENT_ID=your-discord-client-id
DISCORD_GUILD_ID=your-discord-server-id

# Railway (for deployment)
RAILWAY_TOKEN=your-railway-token
RAILWAY_PROJECT_ID=your-railway-project-id

Environment file structure:

bash

# .env.local (local development)
DATABASE_URI=postgresql://localhost:5432/lipaix_dev
PAYLOAD_SECRET=dev-secret-key
PAYLOAD_PUBLIC_SERVER_URL=http://localhost:3000

# .env.production (production deployment)
DATABASE_URI=postgresql://user:pass@host:5432/lipaix_prod
PAYLOAD_SECRET=production-secret-key
PAYLOAD_PUBLIC_SERVER_URL=https://your-domain.com

Step 4: Database Setup

The project uses PostgreSQL as the database. You have several options:

Option 1: Local PostgreSQL (Recommended for development)

bash

# macOS with Homebrew
brew install postgresql
brew services start postgresql

# Create database
createdb lipaix_dev

# Verify connection
psql -d lipaix_dev -c "SELECT version();"

Option 2: Docker PostgreSQL

bash

# Run PostgreSQL in Docker
docker run --name lipaix-postgres \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=lipaix_dev \
  -p 5432:5432 \
  -d postgres:15

# Verify it's running
docker ps

Option 3: Railway PostgreSQL (Production)

Create account at railway.app
Create new project
Add PostgreSQL service
Copy connection string to environment variables

Step 5: Discord Bot Setup

To use the Discord bot features, you'll need to create a Discord application:

Create Discord Application:
- Go to Discord Developer Portal
- Click "New Application"
- Give it a name (e.g., "LIPAIX Bot")
- Copy the Application ID
Create Bot User:
- Go to "Bot" section
- Click "Add Bot"
- Copy the Bot Token
- Enable required permissions
Set up OAuth2:
- Go to "OAuth2" → "URL Generator"
- Select scopes: bot, applications.commands
- Select permissions: Send Messages, Use Slash Commands
- Use the generated URL to invite bot to your server
Update environment variables:

bash

DISCORD_TOKEN=your-bot-token
DISCORD_CLIENT_ID=your-application-id
DISCORD_GUILD_ID=your-server-id

🚀 Running the Project

Development Mode

Start the Next.js web application:

bash

# Start the web app in development mode
pnpm run web:dev

# This will:
# - Start Next.js development server on http://localhost:3000
# - Start PayloadCMS admin interface on http://localhost:3000/admin
# - Enable hot reloading for code changes
# - Show compilation errors in browser

Start the Discord bot:

bash

# In a new terminal, start the Discord bot
pnpm run discord-bot:dev

# This will:
# - Connect to Discord API
# - Register slash commands
# - Listen for interactions
# - Show connection status

Start the documentation site:

bash

# In another terminal, start the documentation
cd docs/vitepress
pnpm run docs:dev

# This will:
# - Start VitePress dev server on http://localhost:3001
# - Enable hot reloading for documentation changes
# - Show the documentation website

Production Build

Build all applications:

bash

# Build the web application
pnpm run web:build

# Build the Discord bot
pnpm run discord-bot:build

# Build the documentation
cd docs/vitepress
pnpm run docs:build

Start production servers:

bash

# Start production web server
pnpm run web:start

# Start production Discord bot
pnpm run discord-bot:start

🧪 Testing Your Setup

Verify Web Application

Open your browser and go to http://localhost:3000
Check the homepage - you should see the LIPAIX website
Visit the admin interface at http://localhost:3000/admin
Check for errors in the browser console and terminal

Verify Discord Bot

Check terminal output - should show "Bot is ready!"
Go to your Discord server - bot should be online
Try a slash command - /dispos or /selecs
Check for errors in the terminal

Verify Database Connection

Check PayloadCMS admin - should load without database errors
Try to create a collection - should work if database is connected
Check terminal logs - should show successful database connections

🔍 Common Issues & Solutions

Port Already in Use

bash

# Check what's using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use a different port
PORT=3001 pnpm run web:dev

Database Connection Failed

bash

# Check if PostgreSQL is running
brew services list | grep postgresql

# Start PostgreSQL if stopped
brew services start postgresql

# Test connection
psql -d lipaix_dev -c "SELECT 1;"

Dependencies Installation Failed

bash

# Clear pnpm cache
pnpm store prune

# Remove node_modules
rm -rf node_modules

# Clear npm cache (if using npm)
npm cache clean --force

# Reinstall
pnpm install

TypeScript Errors

bash

# Generate types
pnpm run generate:types

# Check TypeScript configuration
npx tsc --noEmit

# Restart VS Code TypeScript server
# Cmd+Shift+P → "TypeScript: Restart TS Server"

📚 Next Steps

Now that you have the development environment set up, here's what to explore next:

🏗️ Architecture Guide - Understand how everything works together
🎨 Frontend Development - Learn about Next.js and React
⚙️ Backend & Admin - Understand PayloadCMS and the database
🤖 Discord Bot - Learn about bot functionality
🚀 Deployment Guide - Deploy to production

🆘 Getting Help

If you encounter issues during setup:

Check the Troubleshooting Guide for common solutions
Search existing issues in the GitHub repository
Create a new issue with detailed error information
Join the LIPAIX Discord for community support

📝 Development Workflow

Here's a typical development workflow:

bash

# 1. Start development servers
pnpm run web:dev          # Terminal 1
pnpm run discord-bot:dev  # Terminal 2
pnpm run docs:dev         # Terminal 3

# 2. Make changes to code
# 3. See changes automatically in browser
# 4. Test functionality
# 5. Commit changes
git add .
git commit -m "Add new feature"
git push origin main

# 6. Deploy to production (covered in deployment guide)

🎉 Congratulations! You've successfully set up your LIPAIX development environment. You're now ready to start contributing to the project!

🚀 Getting Started ​

📋 Prerequisites ​

Required Software ​

System Requirements ​

🔧 Installation Steps ​

Step 1: Install Node.js ​

Step 2: Install pnpm ​

Step 3: Install Git ​

Step 4: Install VS Code (Recommended) ​

🏗️ Project Setup ​

Step 1: Clone the Repository ​

Step 2: Install Dependencies ​

Step 3: Environment Configuration ​

Step 4: Database Setup ​

Step 5: Discord Bot Setup ​

🚀 Running the Project ​

Development Mode ​

Production Build ​

🧪 Testing Your Setup ​

Verify Web Application ​

Verify Discord Bot ​

Verify Database Connection ​

🔍 Common Issues & Solutions ​

Port Already in Use ​

Database Connection Failed ​

Dependencies Installation Failed ​

TypeScript Errors ​

📚 Next Steps ​

🆘 Getting Help ​

📝 Development Workflow ​

🚀 Getting Started

📋 Prerequisites

Required Software

System Requirements

🔧 Installation Steps

Step 1: Install Node.js

Step 2: Install pnpm

Step 3: Install Git

Step 4: Install VS Code (Recommended)

🏗️ Project Setup

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Environment Configuration

Step 4: Database Setup

Step 5: Discord Bot Setup

🚀 Running the Project

Development Mode

Production Build

🧪 Testing Your Setup

Verify Web Application

Verify Discord Bot

Verify Database Connection

🔍 Common Issues & Solutions

Port Already in Use

Database Connection Failed

Dependencies Installation Failed

TypeScript Errors

📚 Next Steps

🆘 Getting Help

📝 Development Workflow