Gabriel Gómez Gómez · 20 de septiembre, 2025

Guía paso a paso: crea tu proyecto con Django 5.2 (LTS)

Vamos a crear un proyecto Django 5.2 LTS con buenas prácticas: entorno virtual aislado, ejecución del servidor, creación de una app base y manejo correcto de migraciones. Incluyo extras para PostgreSQL si luego conectas con tu stack Next.js + Django.
1) Requisitos: Python 3.11+ (recomendado 3.12), pip y Git.

python --version
pip --version
git --version

2) Crea y activa un entorno virtual (aísla dependencias). En Windows usa Scripts\activate.

mkdir mi_backend && cd mi_backend
python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows (PowerShell)
# .venv\Scripts\Activate.ps1

3) Actualiza pip e instala Django 5.2.2 (LTS). Congela dependencias en requirements.

python -m pip install --upgrade pip
pip install "Django==5.2.2"
pip freeze > requirements.txt

4) Crea el proyecto base y valida que corre.

django-admin startproject config .
python manage.py migrate
python manage.py runserver 8000

5) Ajustes mínimos en settings: zona horaria MX y español. (Archivo: config/settings.py).

# config/settings.py
LANGUAGE_CODE = "es-mx"
TIME_ZONE = "America/Mexico_City"
USE_I18N = True
USE_TZ = True
ALLOWED_HOSTS = ["localhost", "127.0.0.1"]

6) Crea una app (módulo funcional). Agrega la app a INSTALLED_APPS.
terminalBASH
```
python manage.py startapp core
```

# config/settings.py
INSTALLED_APPS = [
  # Django apps
  "django.contrib.admin",
  "django.contrib.auth",
  "django.contrib.contenttypes",
  "django.contrib.sessions",
  "django.contrib.messages",
  "django.contrib.staticfiles",
  # Tu app
  "core",
]

7) Primer modelo y migraciones. Cada vez que modifiques modelos: makemigrations y luego migrate.

# core/models.py
from django.db import models

class Nota(models.Model):
    titulo = models.CharField(max_length=200)
    creada = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.titulo

python manage.py makemigrations
python manage.py migrate

8) Admin rápido para validar. Crea superusuario y registra el modelo.

# core/admin.py
from django.contrib import admin
from .models import Nota
admin.site.register(Nota)

python manage.py createsuperuser
python manage.py runserver 8000
# Entra a http://127.0.0.1:8000/admin/

9) Cómo ejecutar el proyecto (resumen). Activa el entorno y corre el servidor.

# Cada vez que regreses al proyecto
cd mi_backend
source .venv/bin/activate   # (o .venv\Scripts\Activate.ps1 en Windows)
python manage.py runserver 8000

10) Cómo actualizar las migraciones (cambios en modelos). Orden recomendado:

# 1) Edita tus modelos (models.py)
# 2) Genera migraciones
python manage.py makemigrations
# 3) Aplica migraciones a la base
python manage.py migrate
# Utilidad: ver el estado
python manage.py showmigrations
# Rehacer última migración (si te equivocaste durante desarrollo)
# python manage.py migrate core 0001

11) PostgreSQL (opcional pero recomendado en producción). Instala el driver psycopg[binary] y configura DATABASES.

pip install "psycopg[binary]~=3.2"
pip freeze > requirements.txt

# config/settings.py
import os

DATABASES = {
  "default": {
    "ENGINE": "django.db.backends.postgresql",
    "NAME": os.getenv("PGDATABASE", "mi_db"),
    "USER": os.getenv("PGUSER", "mi_usuario"),
    "PASSWORD": os.getenv("PGPASSWORD", "mi_password"),
    "HOST": os.getenv("PGHOST", "localhost"),
    "PORT": os.getenv("PGPORT", "5432"),
  }
}

echo "PGDATABASE=mi_db" >> .env
echo "PGUSER=mi_usuario" >> .env
echo "PGPASSWORD=mi_password" >> .env
echo "PGHOST=localhost" >> .env
echo "PGPORT=5432" >> .env

12) Archivos estáticos (mínimo). En desarrollo, Django los sirve; en producción usa servidor de archivos o CDN.

# config/settings.py
STATIC_URL = "/static/"
STATICFILES_DIRS = []  # si usas /static/ en la raíz del proyecto

13) Seguridad y orden: usa .gitignore, separa settings por entorno y nunca subas secretos.

curl -s https://www.toptal.com/developers/gitignore/api/python,django > .gitignore

14) Comandos útiles de mantenimiento.

# Shell interactiva con contexto Django
python manage.py shell
# Comprobar errores comunes
python manage.py check
# Probar consultas (perf) con DEBUG off (entorno prod)
python manage.py runserver --insecure

Con esto tienes un backend Django listo: virtualenv, ejecución local y flujo de migraciones claro.