elearning/Backend/.agent/workflows/setup.md

description
How to setup the backend development environment

Setup Development Environment

Follow these steps to setup the E-Learning Platform backend with TypeScript and TSOA on your local machine.

---

Prerequisites

• Node.js 18+ and npm
• Docker and Docker Compose
• Git

---

Step 1: Clone Repository

git clone <repository-url>
cd e-learning/Backend

---

Step 2: Install Dependencies

// turbo

npm install

// turbo Install TypeScript and TSOA:

npm install -D typescript @types/node @types/express ts-node nodemon
npm install tsoa swagger-ui-express

---

Step 3: Initialize TypeScript

// turbo Create tsconfig.json:

npx tsc --init

Update tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

---

Step 4: Configure TSOA

Create tsoa.json:

{
  "entryFile": "src/app.ts",
  "noImplicitAdditionalProperties": "throw-on-extras",
  "controllerPathGlobs": ["src/controllers/**/*.controller.ts"],
  "spec": {
    "outputDirectory": "public",
    "specVersion": 3,
    "securityDefinitions": {
      "jwt": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "routes": {
    "routesDir": "src/routes",
    "middleware": "express",
    "authenticationModule": "./src/middleware/auth.ts"
  }
}

---

Step 5: Setup Environment Variables

Copy example env file:

cp .env.example .env

Edit .env:

# Application
NODE_ENV=development
PORT=4000
APP_URL=http://localhost:4000

# Database
DATABASE_URL=postgresql://postgres:12345678@localhost:5432/elearning_dev

# MinIO/S3
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=admin
S3_SECRET_KEY=12345678
S3_BUCKET_COURSES=courses
S3_BUCKET_VIDEOS=videos
S3_BUCKET_DOCUMENTS=documents
S3_BUCKET_IMAGES=images
S3_BUCKET_ATTACHMENTS=attachments

# JWT
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_EXPIRES_IN=24h

# Email (Mailhog)
SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_FROM=noreply@elearning.local

---

Step 4: Start Docker Services

// turbo

docker compose up -d

This starts:

• PostgreSQL (port 5432)
• MinIO (ports 9000, 9001)
• Mailhog (ports 1025, 8025)
• Adminer (port 8080)

---

Step 6: Run Database Migrations

// turbo

npx prisma migrate dev

---

Step 7: Seed Database

// turbo

npx prisma db seed

This creates:

• Default roles (Admin, Instructor, Student)
• Test users
• Sample categories
• Sample courses

---

Step 8: Generate TSOA Routes

// turbo

npm run tsoa:gen

This generates:

• Routes in src/routes/tsoa-routes.ts
• Swagger spec in public/swagger.json

---

Step 9: Start Development Server

// turbo

npm run dev

Server will start at http://localhost:4000

---

Step 10: Verify Setup

// turbo Test health endpoint:

curl http://localhost:4000/health

// turbo Test login:

curl -X POST http://localhost:4000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}'

---

Access Services

Service	URL	Credentials
Backend API	http://localhost:4000	-
API Docs (Swagger)	http://localhost:4000/api-docs	-
MinIO Console	http://localhost:9001	admin / 12345678
Mailhog UI	http://localhost:8025	-
Adminer	http://localhost:8080	postgres / 12345678

---

Development Commands

# Start dev server (TypeScript)
npm run dev

# Build TypeScript
npm run build

# Generate TSOA routes and Swagger
npm run tsoa:gen

# Run tests
npm test

# Run linter
npm run lint

# Format code
npm run format

# Generate Prisma Client
npx prisma generate

# View database in Prisma Studio
npx prisma studio

# Reset database (WARNING: deletes all data)
npx prisma migrate reset

---

Troubleshooting

Port Already in Use

# Find process using port
lsof -i :4000

# Kill process
kill -9 <PID>

Database Connection Error

# Check if PostgreSQL is running
docker ps | grep postgres

# Check logs
docker logs elearning-postgres

# Restart PostgreSQL
docker restart elearning-postgres

Prisma Client Error

# Regenerate client
npx prisma generate

# Clear node_modules
rm -rf node_modules
npm install

---

Checklist

• Node.js 18+ installed
• Docker installed and running
• Repository cloned
• Dependencies installed
• .env file configured
• Docker services running
• Database migrated
• Database seeded
• Dev server running
• Health check passing
• Login test successful

---

Next Steps

• Read Backend Development Rules
• Follow Create API Endpoint workflow
• Review Agent Skills