SAGA

Herramienta de búsqueda de información en fuentes abiertas, orientada a investigaciones: permite a gente no técnica obtener información técnica (registros DNS, datos de direcciones IP, metadatos de imágenes y cabeceras de correo).

Son dos piezas que se sirven del mismo dominio: la API, en Django + Django REST Framework bajo /api/v1/ (con los flujos de cuenta de django-allauth bajo /_allauth/browser/v1/), y el frontend, una SPA en React + TypeScript que se construye a estáticos servidos por nginx.

Requisitos

• Python 3.12 o superior
• Node 20 o superior (sólo para construir el frontend)
• libmagic (para python-magic): sudo apt-get install -y libmagic1
• Dependencias Python: ver requirements.txt
• Dependencias del frontend: ver frontend/package.json

Con Docker

$ cp .env.example .env          # y completar DJANGO_SECRET_KEY y POSTGRES_PASSWORD
$ docker compose up -d
$ docker compose exec web python manage.py createsuperuser
$ docker compose exec web python manage.py update_geoip_db

Queda publicado en http://localhost:8080 (se cambia con SAGA_HTTP_PORT). El stack son tres servicios: db (PostgreSQL), web (gunicorn) y nginx. El frontend se construye dentro de la imagen; no hace falta tener Node instalado.

Todas las variables de entorno están comentadas en .env.example.

Los $ en el .env se escriben $$. docker compose interpola las variables de ese archivo: un $ sin duplicar hace que el contenedor reciba un valor distinto al del archivo, sin ningún error.

Cuenta de desarrollo

Con SAGA_DEV_USER=1 en el .env el contenedor crea al arrancar una cuenta de superusuario de prueba (SAGA_DEV_USER_NAME/_PASSWORD/_EMAIL), con el email ya verificado. Se niega a correr si DJANGO_HTTPS=1, así que no puede aparecer en un despliegue real.

Sin Docker

1. Crear el entorno virtual e instalar dependencias.

   $ sudo apt-get install -y python3 python3-venv libmagic1
   $ python3 -m venv sagaenv
   $ sagaenv/bin/pip install -r requirements.txt
   

   Hace falta un PostgreSQL con los datos de conexión en DJANGO_DB_*. Para trabajar sin uno, DJANGO_DB_ENGINE=sqlite usa un archivo SQLite.

2. Generar la clave secreta.

   $ sagaenv/bin/python -c "from django.core.management.utils import get_random_secret_key as g; print(g())" > secret_key.key
   

3. Crear la base y un usuario.

   $ sagaenv/bin/python manage.py migrate
   $ sagaenv/bin/python manage.py createsuperuser
   

   Las altas de usuarios por la web están cerradas: los usuarios se crean desde el admin (/admin/) o por consola. La API exige email verificado (marcarlo en el admin, en Accounts > Email addresses).

4. Construir el frontend y correr la aplicación.

   $ cd frontend && npm ci && npm run build && cd ..
   $ sagaenv/bin/python manage.py collectstatic --noinput
   $ DJANGO_DEBUG=1 sagaenv/bin/python manage.py runserver
   

   Sin el build, la aplicación arranca igual pero cualquier ruta del frontend responde 503 (la API y el admin funcionan).

   En producción se sirve con WSGI (gunicorn/uWSGI) detrás de nginx o Apache, que es quien termina TLS y sirve /static/.

Desarrollo del frontend

Con recarga en caliente son dos procesos:

# terminal 1
$ DJANGO_DEBUG=1 DJANGO_HTTPS=0 sagaenv/bin/python manage.py runserver

# terminal 2
$ cd frontend && npm install && npm run dev

Se trabaja en http://localhost:5173; el proxy de Vite manda /api, /_allauth, /admin y /static al backend.

Geolocalización de IPs

La app iploc usa una base local DB-IP Lite City (MMDB), sin clave de API. Se baja con:

$ sagaenv/bin/python manage.py update_geoip_db

Son ~124 MB en disco. DB-IP publica un release por mes, así que conviene un cron.

Tests

$ sagaenv/bin/python manage.py test          # backend
$ cd frontend && npm test                    # frontend

Identidad del sitio

El nombre, el logo, el equipo y el contacto salen de variables de entorno (ver .env.example), no están escritos en el frontend: cambiarlos no exige reconstruirlo.

Licencia

AGPL-3.0. Ver LICENSE.