Skip to main content

​
Prerequisites

Before you begin, make sure you have the following installed:
  • Python 3.11+ — verify with python3 --version
  • pip — included with Python 3.11+
  • Git — to clone the repository
  • mysqlclient system dependencies (for MySQL in production) — on Debian/Ubuntu: sudo apt-get install default-libmysqlclient-dev
For development, the project uses SQLite by default. No database server installation is required.

​
Setup steps

1

Clone the repository

Clone the project and navigate into the backend directory:
git clone <url-del-repositorio>
cd Proyecto_Final-1/backend
2

Create a virtual environment

Create and activate an isolated Python environment:
python3 -m venv .venv
source .venv/bin/activate
Your terminal prompt will change to show (.venv) when the environment is active.
3

Install dependencies

Install all required packages from requirements.txt:
pip install -r requirements.txt
This installs the following key packages:
PackageVersionPurpose
Django5.2.3Web framework
djangorestframework3.16.0REST API
djangorestframework-simplejwt5.5.0JWT authentication
django-cors-headers4.7.0CORS management
mysqlclient2.2.7MySQL driver (production)
Pillow11.2.1Image processing
qrcode8.2QR code generation
python-dotenv0.19.2Environment variables
openpyxl3.1.2Excel export
4

Configure environment variables

The project reads configuration from config/.env. A default file is already provided for development. Review and update it as needed:
config/.env
# Django core
DJANGO_SECRET_KEY='django-insecure-hgc75niihfbvezpl6yw9y3_r^=k+$x&77+eazqw@-x-&ho!plu'
DJANGO_DEBUG=True
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1

# Database (SQLite for development)
DATABASE_ENGINE=django.db.backends.sqlite3
DATABASE_NAME=parque_marino_db.sqlite3

# CORS
DJANGO_CORS_ALLOWED_ORIGINS=http://localhost:5173,http://127.0.0.1:5173,http://localhost:3000,http://127.0.0.1:3000

# JWT
JWT_ACCESS_TOKEN_LIFETIME_MINUTES=5
JWT_REFRESH_TOKEN_LIFETIME_DAYS=1
JWT_ALGORITHM=HS256
Replace DJANGO_SECRET_KEY with a unique, randomly generated key before deploying to any shared or production environment. Never commit a real secret key to version control.
See the Environment variables page for a full reference of all available variables.
5

Run database migrations

Apply all database migrations to create the schema:
python manage.py migrate
Django will create db.sqlite3 in the backend/ directory with all required tables.
6

Create a superuser

Create an admin account to access the Django admin panel at /admin/:
python manage.py createsuperuser
You will be prompted for a username, email address, and password.
7

Seed system roles

The project includes a script that creates the admin and cliente role groups and assigns the appropriate model-level permissions to each:
python create_roles.py
Expected output:
Creando roles básicos del sistema...
Rol 'admin' creado
Rol 'cliente' creado
X permisos asignados al rol 'admin'
X permisos asignados al rol 'cliente'
Rol 'admin' asignado al superusuario: <username>
Proceso completado!
This script must be run after migrations and after creating a superuser. It is idempotent — running it again will not duplicate roles.
8

Start the development server

python manage.py runserver
The API will be available at http://localhost:8000/api/ and the admin panel at http://localhost:8000/admin/.

​
Database configuration

The project supports two database backends.

​
SQLite (development)

The default configuration uses SQLite — no additional setup is required:
config/.env
DATABASE_ENGINE=django.db.backends.sqlite3
DATABASE_NAME=parque_marino_db.sqlite3

​
MySQL (production)

To switch to MySQL, update config/.env and uncomment the MySQL block in config/settings.py:
config/.env
DATABASE_ENGINE=django.db.backends.mysql
DATABASE_NAME=parque_marino_db
DATABASE_USER=root
DATABASE_PASSWORD=your_password
DATABASE_HOST=localhost
DATABASE_PORT=3306
The config/settings.py file currently uses a hardcoded SQLite configuration. To use MySQL, uncomment the MySQL DATABASES block in settings.py and comment out the SQLite block. The MySQL configuration reads from the environment variables shown above.
The mysqlclient package is already included in requirements.txt and handles the connection.

​
Useful management commands

# Create new migrations after model changes
python manage.py makemigrations

# Apply pending migrations
python manage.py migrate

# Open the Django shell
python manage.py shell

# Run tests
python manage.py test

# Collect static files (production)
python manage.py collectstatic

# Migrate media files to Supabase Storage
python manage.py migrate_to_supabase --backup

​
Media file storage

Uploaded files are stored locally under media/ during development: 
backend/media/
├── documentos/        # Uploaded documents
├── exhibitions/       # Exhibition images
├── profile_pics/      # User profile photos
├── programas/         # Educational programme files
├── qr_codes/          # Generated QR codes
├── servicios-educativos/  # Educational service files
└── species/           # Species images
For production, the project includes a Supabase Storage backend (config/supabase_storage.py). See the SUPABASE_STORAGE_README.md file in the backend directory for configuration instructions.

​
Troubleshooting

If you encounter migration conflicts, you can reset the API migrations. This deletes all data in the database.
python manage.py migrate --fake api zero
python manage.py migrate
If a package fails to install or causes a conflict, reinstall all dependencies cleanly:
pip uninstall -r requirements.txt -y
pip install -r requirements.txt
On Unix systems, ensure the media/ directory is writable by the process running the server:
chmod 755 media/
On Debian/Ubuntu, install the MySQL development headers before running pip install:
sudo apt-get install default-libmysqlclient-dev build-essential
On macOS with Homebrew:
brew install mysql-client
export PKG_CONFIG_PATH="/usr/local/opt/mysql-client/lib/pkgconfig"

Build docs developers (and LLMs) love

Get started for freeTalk to us