Instalación¶

Requisitos¶

Python 3.14+
Docker + Docker Compose (para Redis y Mailpit en local).
Una base de datos alcanzable. El engine es agnóstico del motor (MySQL/MariaDB, PostgreSQL, Oracle, SQL Server, SQLite); se elige con DATABASE_URL.
(Recomendado) uv como gestor de entorno y deps.
(Opt-in) Frontend Vite — solo si usas el asset-pipeline o los microfrontends (surcos): Node >=22.13 (el .nvmrc fija 22: pnpm 11 usa node:sqlite) y pnpm 11. Un proyecto que solo renderiza HTML con Jinja no los necesita. Ver Vite y assets.

Opción A — con `uv` (recomendada)¶

uv sync

Crea el entorno y resuelve dependencias (incluidas las de desarrollo) desde pyproject.toml / uv.lock. Para correr cualquier comando, antepón uv run (no necesitas activar el venv):

uv run python jornal list
uv run pytest

Solo producción (sin herramientas de dev):

uv sync --no-dev

Opción B — Python + venv (pip)¶

python3.14 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -e .                   # dependencias de ejecución
pip install --group dev            # herramientas de dev (pip >= 25.1)
# pip más viejo:  pip install pytest ruff mypy import-linter

Con el venv activado, corre los comandos sin el prefijo uv run.

Drivers de base de datos¶

El core es agnóstico del motor: instala el extra del tuyo (sqlite no necesita nada, viene en Python):

uv sync --extra mysql         # MySQL / MariaDB (pymysql)
uv sync --extra postgres      # PostgreSQL (psycopg v3)
uv sync --extra oracle        # Oracle (oracledb)
uv sync --extra mssql         # SQL Server (pyodbc; requiere el ODBC Driver del SO)

Con pip: pip install ".[postgres]".

El motor se elige con el prefijo de DATABASE_URL (ver Base de datos):

mysql+pymysql://...        postgresql+psycopg://...      oracle+oracledb://...
mssql+pyodbc://...         sqlite:///app.db

Configuración mínima¶

cp .env.example .env

Como mínimo necesitas DATABASE_URL (es la única variable sin default). Ajusta el resto según tu entorno. Ver Configuración.

Levantar la infraestructura¶

Docker solo corre infraestructura (Redis + Mailpit; RabbitMQ opcional). La app corre en el host.

docker compose up -d        # Redis (6379) + Mailpit (SMTP 1025, UI http://localhost:8025)

(Opt-in) Frontend Vite¶

Solo si tu proyecto trae surcos (microfrontends). Instala las dependencias del workspace pnpm desde la raíz y, si quieres HMR, levanta el dev server de un surco:

pnpm install                     # instala TODO el workspace (surcos/*)
pnpm --filter demo-spa dev       # dev server con HMR de un surco
pnpm -r build                    # buildea todos los surcos (modo prod)

Ver Vite y assets y Microfrontends (surcos).

Verificar la instalación¶

uv run python jornal list                 # debe listar los comandos
uv run pytest                             # la suite debe pasar (sin BD)
uv run python jornal serve                # levanta la API en http://localhost:8000

Siguiente paso¶

Configuración.