Installation & Setup

Overview

This guide covers the complete installation process for Relaciona, including all dependencies, database setup, cloud storage configuration, and environment variables.

Looking for a quick start? See the Quickstart Guide to get up and running in minutes.

System Requirements

Python

Version 3.11+ requiredCheck version: python3 --version

PostgreSQL

Version 12+ recommendedAlternative: SQLite for local dev only

Git

For cloning the repositoryCheck version: git --version

Node.js (Optional)

Only if customizing frontendUsed for Tailwind CSS compilation

Step 1: Python Installation

macOS

# Using Homebrew
brew install [email protected]

# Verify installation
python3 --version

Linux (Ubuntu/Debian)

# Update package list
sudo apt update

# Install Python 3.11
sudo apt install python3.11 python3.11-venv python3-pip

# Verify installation
python3.11 --version

Windows

Download Python 3.11+ from python.org
Run installer and check “Add Python to PATH”
Verify: python --version

Step 2: PostgreSQL Setup

Relaciona uses PostgreSQL for production. SQLite can be used for local testing but is not recommended for production.

Install PostgreSQL

# Using Homebrew
brew install postgresql@15

# Start PostgreSQL service
brew services start postgresql@15

Create Database

# Access PostgreSQL as postgres user
sudo -u postgres psql

# Or on Windows:
psql -U postgres

Inside the PostgreSQL shell:

-- Create database
CREATE DATABASE relaciona_db;

-- Create user (optional, recommended for production)
CREATE USER relaciona_user WITH PASSWORD 'secure_password_here';

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE relaciona_db TO relaciona_user;

-- Exit
\q

Replace secure_password_here with a strong password. Never commit this password to version control.

Step 3: Clone and Setup Project

Clone Repository

git clone https://github.com/dgarridor05/AplicacionPracticas.git
cd AplicacionPracticas

Create Virtual Environment

python3 -m venv venv
source venv/bin/activate

Your terminal prompt should now show (venv) indicating the virtual environment is active.

Install Dependencies

pip install --upgrade pip
pip install -r requirements.txt

Key dependencies installed:

Django 4.2.27 - Web framework
psycopg2-binary - PostgreSQL database adapter
django-cloudinary-storage - Cloud image storage
whitenoise - Static file serving
gunicorn - WSGI HTTP server for production
python-dotenv - Environment variable management
dj-database-url - Database URL parser

Step 4: Cloudinary Configuration

Relaciona uses Cloudinary to store student profile pictures. This is required for profile picture uploads.

Create Cloudinary Account

Sign up for free at cloudinary.com
Navigate to your Dashboard
Copy your credentials:
- Cloud Name
- API Key
- API Secret

Configure Cloudinary

Add these to your .env file (created in next step):

CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

Cloudinary’s free tier includes 25 GB storage and 25 GB monthly bandwidth - more than enough for most classrooms!

Step 5: Environment Variables

Create a .env file in the project root (same directory as manage.py):

touch .env

Development Configuration

Add the following to your .env file:

.env

# ==========================================
# Django Core Settings
# ==========================================
SECRET_KEY=django-insecure-your-very-long-random-secret-key-here
DEBUG=True

# ==========================================
# Database Configuration (PostgreSQL)
# ==========================================
DB_NAME=relaciona_db
DB_USER=relaciona_user
DB_PASSWORD=your_database_password
DB_HOST=localhost
DB_PORT=5432

# ==========================================
# Cloudinary (Profile Pictures)
# ==========================================
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

Generate SECRET_KEY

Generate a secure secret key:

python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

Copy the output and use it as your SECRET_KEY value.

Security Notice:

Never commit .env to version control
The .gitignore file already excludes .env
Use different keys for development and production
Set DEBUG=False in production

Production Configuration

For production, additional settings are required:

.env (Production)

# Django Core
SECRET_KEY=production-secret-key-different-from-dev
DEBUG=False

# Database (use production credentials)
DB_NAME=relaciona_production
DB_USER=prod_user
DB_PASSWORD=strong_production_password
DB_HOST=your-rds-endpoint.amazonaws.com  # Example for AWS RDS
DB_PORT=5432

# Cloudinary (can use same account or separate)
CLOUDINARY_CLOUD_NAME=production_cloud
CLOUDINARY_API_KEY=prod_api_key
CLOUDINARY_API_SECRET=prod_api_secret

See Environment Variables Reference for complete details.

Step 6: Database Migrations

Apply database migrations to create all required tables:

python manage.py migrate

You should see output like:

Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying accounts.0001_initial... OK
  Applying teachers.0001_initial... OK
  Applying quizzes.0001_initial... OK
  Applying minigames.0001_initial... OK
  ...

This creates tables for:

accounts.UserProfile - Student and teacher accounts (see accounts/models.py:5)
teachers.ClassGroup - Classes with invite codes (see teachers/models.py:10)
quizzes - VARK and Chapman assessments
minigames - Game sessions and scores

Step 7: Create Superuser

Create an admin account to access Django admin panel:

python manage.py createsuperuser

Enter:

Username
Email (optional)
Password (entered twice)

The superuser can access Django admin at /admin/ to manage all data.

Step 8: Collect Static Files

Collect static files for production serving:

python manage.py collectstatic --no-input

This copies all CSS, JavaScript, and image files to staticfiles/ directory for WhiteNoise to serve.

In development with DEBUG=True, Django serves static files automatically. This step is mainly for production.

Step 9: Run Development Server

Start the Django development server:

python manage.py runserver

Access Relaciona at:

Application: http://localhost:8000
Admin Panel: http://localhost:8000/admin

Development vs Production

Development Setup

Characteristics

DEBUG=True in settings
SQLite database option available
Django serves static files
Detailed error pages
Auto-reload on code changes
python manage.py runserver

When to use

Local development
Testing features
Debugging issues
Learning the platform

Production Setup

Characteristics

DEBUG=False in settings
PostgreSQL database required
WhiteNoise serves static files
Generic error pages
Gunicorn WSGI server
SSL/HTTPS recommended

When to use

Live classroom use
Multiple simultaneous users
Data persistence required
Public internet access

See Cloud Deployment for production deployment guides.

Troubleshooting

Database Connection Errors

Error: django.db.utils.OperationalError: could not connect to server

Solution: Check PostgreSQL is running

# macOS
brew services list
brew services start postgresql@15

# Linux
sudo systemctl status postgresql
sudo systemctl start postgresql

# Windows - check Services app

Solution: Verify credentials

Check .env file has correct DB_NAME, DB_USER, DB_PASSWORD
Test connection:

psql -U relaciona_user -d relaciona_db -h localhost

Solution: Check database exists

-- List all databases
psql -U postgres -c "\l"

-- Create if missing
psql -U postgres -c "CREATE DATABASE relaciona_db;"

Cloudinary Upload Errors

Error: Profile pictures fail to upload

Verify Cloudinary credentials

Check .env has all three Cloudinary variables
Verify credentials at cloudinary.com/console
Test in Django shell:

python manage.py shell
>>> from django.conf import settings
>>> print(settings.CLOUDINARY_STORAGE)

Check Cloudinary storage setting

In relaciona/settings.py:49, verify:

DEFAULT_FILE_STORAGE = 'cloudinary_storage.storage.MediaCloudinaryStorage'

Import Errors

Error: ModuleNotFoundError: No module named 'django'

Virtual environment not activated

Make sure you see (venv) in your terminal:

# Activate it
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

Dependencies not installed

pip install -r requirements.txt

Migration Errors

Error: Conflicting migrations detected

Reset migrations (development only)

This deletes all data. Only use in development.

# Drop and recreate database
psql -U postgres -c "DROP DATABASE relaciona_db;"
psql -U postgres -c "CREATE DATABASE relaciona_db;"

# Remove migration files (keep __init__.py)
find . -path "*/migrations/*.py" -not -name "__init__.py" -delete
find . -path "*/migrations/*.pyc" -delete

# Recreate migrations
python manage.py makemigrations
python manage.py migrate

Static Files Not Loading

Error: CSS/JavaScript not loading in production

Run collectstatic

python manage.py collectstatic --no-input

Check WhiteNoise configuration

Verify in relaciona/settings.py:52-53:

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'whitenoise.middleware.WhiteNoiseMiddleware',  # Must be here
    ...
]

Docker Installation (Alternative)

Relaciona includes Docker support for containerized deployment.

Using Docker

# Build image
docker build -t relaciona .

# Run container
docker run -p 8000:8000 \
  -e SECRET_KEY=your-secret-key \
  -e DB_HOST=host.docker.internal \
  -e DB_NAME=relaciona_db \
  relaciona

See Dockerfile for the complete configuration.

Using Docker Compose (Coming Soon)

A docker-compose.yml configuration for running Relaciona with PostgreSQL is planned.

Next Steps

Environment Variables

Complete reference for all configuration options

Database Setup

Advanced database configuration and backup strategies

Cloud Deployment

Deploy to AWS Elastic Beanstalk, Vercel, or Render

Creating Classes

Start using Relaciona with your first class

Having trouble? Check the GitHub Issues or create a new issue with your error details.

Get Started

For Teachers

For Students

Features

​Overview

​System Requirements

Python

PostgreSQL

Git

Node.js (Optional)

​Step 1: Python Installation

​macOS

​Linux (Ubuntu/Debian)

​Windows

​Step 2: PostgreSQL Setup

​Install PostgreSQL

​Create Database

​Step 3: Clone and Setup Project

​Clone Repository

​Create Virtual Environment

​Install Dependencies

​Step 4: Cloudinary Configuration

​Create Cloudinary Account

​Configure Cloudinary

​Step 5: Environment Variables

​Development Configuration

​Generate SECRET_KEY

​Production Configuration

​Step 6: Database Migrations

​Step 7: Create Superuser

​Step 8: Collect Static Files

​Step 9: Run Development Server

​Development vs Production

​Development Setup

​Production Setup

​Troubleshooting

​Database Connection Errors

​Cloudinary Upload Errors

​Import Errors

​Migration Errors

​Static Files Not Loading

​Docker Installation (Alternative)

​Using Docker

​Using Docker Compose (Coming Soon)

​Next Steps

Environment Variables

Database Setup

Cloud Deployment

Creating Classes

Build docs developers (and LLMs) love

Overview

System Requirements

Step 1: Python Installation

macOS

Linux (Ubuntu/Debian)

Windows

Step 2: PostgreSQL Setup

Install PostgreSQL

Create Database

Step 3: Clone and Setup Project

Clone Repository

Create Virtual Environment

Install Dependencies

Step 4: Cloudinary Configuration

Create Cloudinary Account

Configure Cloudinary

Step 5: Environment Variables

Development Configuration

Generate SECRET_KEY

Production Configuration

Step 6: Database Migrations

Step 7: Create Superuser

Step 8: Collect Static Files

Step 9: Run Development Server

Development vs Production

Development Setup

Production Setup

Troubleshooting

Database Connection Errors

Cloudinary Upload Errors

Import Errors

Migration Errors

Static Files Not Loading

Docker Installation (Alternative)

Using Docker

Using Docker Compose (Coming Soon)

Next Steps