Getting Started Quick Start

🚀 Quick Start - Your First 15 Minutes with EduLite

Get EduLite running on your computer in 15 minutes or less using Docker. We'll guide you through every step!

🎯 What You'll Achieve

In the next 15 minutes, you'll:

• ✅ Get the EduLite code on your computer
• ✅ Start all services with one command (backend, frontend, database, Redis)
• ✅ See EduLite running in your browser
• ✅ Be ready to make your first contribution!

---

📋 Before You Start

Required Software

You need these programs installed:

Software	Version	Check if installed	Download
Git	Any recent	git --version	Download (Windows: includes Git Bash)
Docker	20.10+	docker --version	Download
Docker Compose	2.0+	docker compose version	Included with Docker Desktop
Make	Any recent	make --version	Pre-installed on Linux/Mac. Windows: see below ⬇️

Quick Check

Open your terminal and run:

git --version && docker --version && docker compose version && make --version

If all four show version numbers, you're ready! If not, install the missing software.

🪟 Windows Users - Important!

The make command won't work in Command Prompt or PowerShell. You have three options:

1. Git Bash (Recommended - Easiest)

   • Already installed with Git for Windows!
   • Open Git Bash terminal (not Command Prompt)
   • All make commands will work
   • Verify: make --version

2. Install Make separately

   • Via Chocolatey: choco install make
   • Via Scoop: scoop install make
   • Then use PowerShell or Command Prompt

3. WSL2 (Windows Subsystem for Linux)

   • Install WSL2
   • Get a full Linux environment
   • All commands work natively

For the rest of this guide, Windows users should use Git Bash or WSL2.

---

🏃 Let's Get Started!

Step 1: Get the Code (2 minutes)

Fork the repository (creates your own copy)

1. Go to github.com/ibrahim-sisar/EduLite
2. Click the "Fork" button (top right)
3. Wait for GitHub to create your copy

Clone to your computer

git clone https://github.com/YOUR_USERNAME/EduLite.git
cd EduLite

Replace YOUR_USERNAME with your GitHub username!

Check you're in the right place

ls

You should see folders like backend/, Frontend/, docker/ and files like README.md, Makefile

---

Step 2: Start EduLite with Docker (10 minutes)

This is where the magic happens! One command does everything.

2.1 Quick Start

make quickstart

What does this do?

• Creates a .env file with auto-generated secure secrets
• Builds Docker images for backend and frontend
• Starts 4 services:
  • 🐍 Backend (Django + Daphne) on port 8000
  • ⚛️ Frontend (React + Vite) on port 5173
  • 🐘 PostgreSQL database on port 5433
  • 📮 Redis (for WebSockets) on port 6380
• Runs database migrations automatically
• Collects static files

First time? This takes 5-10 minutes to download and build everything. Grab a coffee! ☕

2.2 Watch the Magic Happen

You'll see output like:

✓ Creating .env file...
✓ Building Docker images...
✓ Starting services...
✓ Running migrations...
✓ Collecting static files...

All services are up and running!

---

Step 3: See EduLite in Action! (1 minute)

1. Open your browser
2. Go to http://localhost:5173/
3. You should see the EduLite homepage!

🎉 Congratulations! EduLite is running on your computer!

---

🔍 Quick Checks

All Services Running?

Check service status:

make ps

You should see all 4 services with status "Up" and "healthy":

NAME               STATUS
edulite-backend    Up 2 minutes (healthy)
edulite-frontend   Up 2 minutes
edulite-postgres   Up 2 minutes (healthy)
edulite-redis      Up 2 minutes (healthy)

Can You Access?

• ✅ Frontend: Beautiful EduLite interface at http://localhost:5173/
• ✅ Backend API: API root at http://localhost:8000/api/
• ✅ Health Check: System status at http://localhost:8000/api/health/
• ✅ Admin Panel: Django admin at http://localhost:8000/admin/ (after creating superuser)

---

🚦 Common Issues & Quick Fixes

"Port already in use" Error

Problem: Another service is using ports 8000, 5173, 5433, or 6380

Solution:

1. Find what's using the port (example for port 8000):

   # On Linux/Mac (or Git Bash on Windows)
   lsof -i :8000
   
   # On Windows (Command Prompt/PowerShell)
   netstat -ano | findstr :8000

2. Option A: Stop the conflicting service

   • If it's an old EduLite instance: make down
   • If it's another service: stop that service or change its port

3. Option B: Change EduLite's ports (recommended if you need both services)

   Create docker/docker-compose.override.yml:

   services:
     backend:
       ports:
         - "8001:8000"  # Change host port to 8001
     
     frontend:
       ports:
         - "5174:5173"  # Change host port to 5174
     
     postgres:
       ports:
         - "5434:5432"  # Change host port to 5434
     
     redis:
       ports:
         - "6381:6379"  # Change host port to 6381

   Then restart:

   make down
   make up

   Access frontend at http://localhost:5174/ and backend at http://localhost:8001/

"Docker daemon not running"

Problem: Docker isn't started

Solution:

• Windows/Mac: Start Docker Desktop
• Linux: sudo systemctl start docker

Build Errors

Problem: Docker build fails

Solution:

# Clean everything and rebuild
make clean
make build
make up

Permission Denied (Linux)

Problem: Docker requires sudo

Solution:

# Add your user to docker group (one-time setup)
sudo usermod -aG docker $USER
newgrp docker

# Or use sudo with make
sudo make quickstart

Services Keep Restarting

Problem: A service fails health checks

Solution:

# Check logs to see what's wrong
make logs

# View specific service logs
make logs-back      # Backend logs
make logs-front     # Frontend logs
make logs-db        # PostgreSQL logs
make logs-redis     # Redis logs

"make: command not found" (Windows)

Problem: Windows Command Prompt or PowerShell doesn't recognize make

Solution:

This means you're not using the right terminal. Choose one:

1. Use Git Bash instead (Recommended)

   • Close Command Prompt/PowerShell
   • Open Git Bash from Start Menu
   • Navigate to project: cd /c/path/to/EduLite
   • Run make quickstart

2. Install Make and continue

   # Using Chocolatey
   choco install make
   
   # Or using Scoop
   scoop install make

3. Use Docker Compose directly (without make)

   cd docker
   docker compose up -d

---

🎯 What's Next?

Now that EduLite is running:

1. Create an Admin User

make createsuperuser

Follow the prompts to create an admin account. Use this to access http://localhost:8000/admin/

2. Make Your First Contribution!

• See First-Contribution.md - Fix a typo in 15 minutes!

3. Explore the Codebase

• Frontend code: Frontend/EduLiteFrontend/src/
• Backend code: backend/EduLite/
• Docker setup: docker/

4. Join the Community

• Discord - Get help in real-time
• GitHub Discussions - Share ideas

5. Choose Your Path

• Frontend Developer Guide - React, UI/UX
• Backend Developer Guide - Django, APIs
• DevOps/Infrastructure - Docker, CI/CD

---

📝 Quick Reference

Daily Development Commands

# Start all services
make up

# Stop all services
make down

# View logs (all services, live updates)
make logs

# Backend shell (Django)
make shell

# Frontend shell
make shell-front

# Run migrations
make migrate

# Create superuser
make createsuperuser

# Run backend tests
make test

# Run frontend tests
make test-front

# Rebuild containers
make build

# Rebuild from scratch (no cache)
make rebuild

# Clean everything (including volumes/data)
make clean

Useful Commands

# Check service status
make ps

# Restart all services
make restart

# View backend logs only
make logs-back

# View frontend logs only
make logs-front

# Access Django shell
make shell

# Access database shell
make shell-db

Hot Reload (Auto-Refresh)

Both frontend and backend support hot reload:

• Frontend: Saves to .jsx/.tsx files auto-refresh browser
• Backend: Saves to .py files auto-restart Django server

Just edit and save - changes appear automatically! 🔥

---

🏗️ Project Structure

EduLite/
├── backend/              # Django backend
│   ├── EduLite/         # Main Django project
│   │   ├── settings.py  # Backend configuration
│   │   ├── health.py    # Health check endpoint
│   │   └── ...
│   ├── users/           # User management
│   ├── courses/         # Course management
│   ├── chat/            # Real-time chat
│   └── requirements.txt # Python dependencies
├── Frontend/            # React frontend
│   └── EduLiteFrontend/
│       ├── src/         # React components
│       │   ├── pages/   # Page components
│       │   ├── components/ # Reusable components
│       │   └── services/   # API services
│       └── package.json # JavaScript dependencies
├── docker/              # Docker configuration
│   ├── docker-compose.yml        # Orchestrates all services
│   ├── .env.example              # Environment template
│   ├── backend/Dockerfile        # Backend image
│   ├── frontend/Dockerfile       # Frontend image
│   └── README.md                 # Detailed Docker docs
├── Makefile             # Convenient commands
└── README.md            # Project overview

---

🔧 Development Workflow

Making Changes

1. Create a branch

   git checkout -b your-name-feature-name

2. Make your changes

   • Edit files in backend/ or Frontend/
   • Changes appear automatically (hot reload)

3. Test your changes

   make test  # Run backend tests

4. Commit and push

   git add .
   git commit -m "Description of changes"
   git push origin your-name-feature-name

5. Open a Pull Request

   • Go to your fork on GitHub
   • Click "New Pull Request"
   • We'll review it together!

Stopping Development

When you're done for the day:

make down

This stops all containers but keeps your data (database, uploads, etc.)

Starting Again

Next time you want to work:

make up

Everything starts up with your data intact!

---

💡 Pro Tips

1. View Live Logs

make logs-follow

See what's happening in real-time. Press Ctrl+C to stop.

2. Clean Database & Start Fresh

make clean  # Deletes ALL data including database
make up
make migrate
make createsuperuser

⚠️ Warning: make clean deletes everything including your database!

3. Access Container Shells

# Django shell (Python REPL with Django loaded)
make shell

# Bash in backend container (for advanced debugging)
make shell
# Note: 'make shell' opens bash in backend. For Django shell, use: python manage.py shell

# Shell in frontend container
make shell-front

4. Check Health Status

curl http://localhost:8000/api/health/ | python3 -m json.tool

Should return:

{
    "status": "healthy",
    "service": "edulite-backend",
    "checks": {
        "database": "ok",
        "redis": "ok"
    }
}

5. Customize Your Setup

Create docker/docker-compose.override.yml:

services:
  backend:
    environment:
      DEBUG: "True"

See docker/docker-compose.override.yml.example for more examples.

---

🆘 Still Stuck?

Don't worry! We've all been there.

1. Check the logs

   make logs

2. Read the detailed docs

   • docker/README.md - Comprehensive Docker documentation
   • backend/CODING_STANDARDS.md - Backend coding standards

3. Ask for help

   • Take a screenshot of your error
   • Join our Discord
   • Post in #help channel
   • Someone will help within minutes!

4. Search existing issues

   • Check GitHub Issues
   • Someone might have had the same problem!

Remember: Every expert was once a beginner. Your questions help us improve documentation for the next person!

---

🎓 Next Steps

Congratulations on taking your first step with EduLite! You're now part of a global community building education for everyone.

Recommended Learning Path

1. ✅ You are here: Got EduLite running
2. 📖 Read Vision & Mission - Understand what we're building
3. 🌟 Complete First Contribution - Make your first PR
4. 🎨 Choose your track:
   • Frontend: React, TypeScript, Tailwind CSS
   • Backend: Django, REST APIs, WebSockets
   • DevOps: Docker, CI/CD, Testing

Welcome aboard! 🎓

---

💚 The journey of a thousand miles begins with a single step. You just took yours!