Installation

Overview

This guide walks you through setting up the complete development environment for the Calculus Learning Platform, including both the Vue 3 frontend and FastAPI backend.

This guide is for developers who want to contribute to the platform or run it locally. If you’re a student or professor just using the platform, see the Quick Start guide instead.

Prerequisites

Before you begin, ensure you have the following installed:

Required Software

Node.js

Version 20.19.0+ or 22.12.0+

Python

Version 3.8+ recommended

PostgreSQL

Version 12+ recommended

Verify Installations

Check that you have the correct versions:

node --version
# Should output v20.19.0 or higher

Installation Steps

Clone the Repository

Clone the project repository to your local machine:

git clone <repository-url>
cd <project-directory>

Replace <repository-url> with the actual Git repository URL provided by your team.

Install Frontend Dependencies

Navigate to the project root and install the Vue 3 frontend dependencies:

npm install

This will install the following key packages:

vue (3.5.22) - Core Vue framework
vue-router (4.6.3) - Client-side routing
vite (7.1.11) - Build tool and dev server
axios (1.13.2) - HTTP client for API requests
tailwindcss (4.1.16) - CSS framework
@vitejs/plugin-vue - Vite plugin for Vue SFCs

Install Backend Dependencies

Navigate to the backend directory and install Python dependencies:

cd back
pip install -r requirements.txt

Or using Python 3 explicitly:

pip3 install -r requirements.txt

This installs:

fastapi - Modern web framework for building APIs
uvicorn - ASGI server for running FastAPI
psycopg2-binary - PostgreSQL adapter for Python
pydantic - Data validation using Python type hints
python-multipart - For handling file uploads

Consider using a virtual environment to isolate dependencies:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Configure the Database

Set up your PostgreSQL database:

Create the Database

psql -U postgres
CREATE DATABASE calculus_platform;
\q

Update Database Connection

Open back/main.py and locate the conectar_bd() function (line 104):

back/main.py

def conectar_bd():
    try:
        conn = psycopg2.connect(
            host="localhost",          # Change from remote host
            database="calculus_platform",  # Your local database name
            user="your_username",      # Your PostgreSQL username
            password="your_password",  # Your PostgreSQL password
            port=5432,
            sslmode="require"          # Optional for local dev
        )
        return conn
    except Exception as e:
        print(f"Error conectando a la BD: {e}")
        return None

Never commit database credentials to version control! Consider using environment variables:

import os

conn = psycopg2.connect(
    host=os.getenv("DB_HOST", "localhost"),
    database=os.getenv("DB_NAME", "calculus_platform"),
    user=os.getenv("DB_USER", "postgres"),
    password=os.getenv("DB_PASSWORD"),
    port=int(os.getenv("DB_PORT", 5432))
)

Create Database Tables

Create the required database schema:

-- Users table
CREATE TABLE usuarios (
    email VARCHAR(255) PRIMARY KEY,
    password VARCHAR(255) NOT NULL,
    nombre VARCHAR(255),
    apellidos VARCHAR(255)
);

-- Forum response tables
CREATE TABLE respuestas_foro1 (
    id SERIAL PRIMARY KEY,
    email VARCHAR(255) REFERENCES usuarios(email),
    r1 TEXT,
    r2 TEXT,
    r3 TEXT,
    r4 TEXT,
    r5 TEXT,
    r6 TEXT,
    fecha TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Create similar tables for foro2, foro3, foro4, foro5, foro6
-- Also create tables: examen1, examen2, feedback

Forum 3 has a special table structure with additional columns for table data (t6_r1_c1, t6_r1_c2, etc.).Forum 5 includes BYTEA columns for image storage: imagen_pregunta_3, imagen_1, imagen_2, imagen_3.

Run the Backend Server

Start the FastAPI backend with Uvicorn:

cd back
uvicorn main:app --reload --host 127.0.0.1 --port 8000

Or use the Python command directly:

python main.py

You should see output like:

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using StatReload
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

The --reload flag enables auto-reloading when you make code changes.

Run the Frontend Server

In a new terminal, start the Vite development server:

npm run dev

The frontend will start on http://localhost:5173 (default Vite port):

VITE v7.1.11  ready in 234 ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
➜  press h + enter to show help

Access the Application

Open your browser and navigate to:

http://localhost:5173

You should see the login page. Test the installation by:

Creating a test account
Logging in
Navigating to Forum 1
Verifying the backend connection is working

The frontend makes API calls to the backend at the URL specified in the Vue components (currently https://proyecto-ingenieria-software-6ccv.onrender.com). For local development, update these URLs to http://127.0.0.1:8000.

Configuration

Update API Base URL

For local development, you’ll need to update API endpoints in the Vue components:

const urlBase = "https://proyecto-ingenieria-software-6ccv.onrender.com";

Files to update:

src/views/Login.vue (line 277)
src/views/foro_1.vue (line 394, 427, 462)
All other forum components

Consider creating an environment variable for the API base URL:

const urlBase = import.meta.env.VITE_API_URL || "http://127.0.0.1:8000";

Then create a .env.local file:

VITE_API_URL=http://127.0.0.1:8000

CORS Configuration

The backend is already configured to accept requests from any origin (line 16-22 in main.py):

back/main.py

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # Allow all origins
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

In production, restrict allow_origins to specific domains:

allow_origins=["https://your-frontend-domain.com"]

Building for Production

Frontend Build

npm run build

This creates an optimized production build in the dist/ directory.

Preview Production Build

npm run preview

Backend Deployment

For production deployment, run Uvicorn without the --reload flag:

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

Consider using a process manager like Supervisor or systemd for production deployments.

Troubleshooting

Frontend Issues

Error: Cannot find module 'vue'

Make sure you’ve installed all dependencies:

npm install

Port 5173 already in use

Kill the process using that port or specify a different port:

npm run dev -- --port 3000

API requests failing

Verify:

Backend is running on port 8000
API base URL is correct in Vue components
No CORS errors in browser console

Backend Issues

Error: No module named 'fastapi'

Install Python dependencies:

pip install -r requirements.txt

Database connection error

Check:

PostgreSQL is running
Database credentials are correct in main.py
Database exists and tables are created

Port 8000 already in use

Find and kill the process, or use a different port:

uvicorn main:app --reload --port 8001

Development Workflow

Recommended Setup

Terminal 1: Run backend with auto-reload
```
cd back && uvicorn main:app --reload
```
Terminal 2: Run frontend with hot module replacement
```
npm run dev
```
Terminal 3: Available for database commands, git, etc.

Code Structure

project-root/
├── src/                  # Vue 3 frontend
│   ├── views/           # Page components (Login, Forum pages)
│   ├── imagenes/        # Image assets
│   └── main.js          # Vue app entry point
├── back/                # FastAPI backend
│   └── main.py          # API routes and database logic
├── package.json         # Frontend dependencies
├── requirements.txt     # Backend dependencies
├── vite.config.js       # Vite configuration
└── tailwind.config.js   # Tailwind CSS configuration

Getting Started

Core Features

User Roles

Deployment

Overview

Prerequisites

Required Software

Node.js

Python

PostgreSQL

Verify Installations

Installation Steps

Create the Database

Update Database Connection

Configuration

Update API Base URL

CORS Configuration

Building for Production

Frontend Build

Preview Production Build

Backend Deployment

Troubleshooting

Frontend Issues

Backend Issues

Development Workflow

Recommended Setup

Code Structure

Next Steps

API Reference

Quick Start

Build docs developers (and LLMs) love

Getting Started

Core Features

User Roles

Deployment

​Overview

​Prerequisites

​Required Software

Node.js

Python

PostgreSQL

​Verify Installations

​Installation Steps

​Create the Database

​Update Database Connection

​Configuration

​Update API Base URL

​CORS Configuration

​Building for Production

​Frontend Build

​Preview Production Build

​Backend Deployment

​Troubleshooting

​Frontend Issues

​Backend Issues

​Development Workflow

​Recommended Setup

​Code Structure

​Next Steps

API Reference

Quick Start

Build docs developers (and LLMs) love

Overview

Prerequisites

Required Software

Verify Installations

Installation Steps

Create the Database

Update Database Connection

Configuration

Update API Base URL

CORS Configuration

Building for Production

Frontend Build

Preview Production Build

Backend Deployment

Troubleshooting

Frontend Issues

Backend Issues

Development Workflow

Recommended Setup

Code Structure

Next Steps