Despliegue y operación técnica

1. Variables de entorno

1. Duplica .env.example (si existe) o usa .env como base. Los campos importantes provienen de app/core/settings.py:
2. POSTGRES_*, REDIS_*, MONGODB_*
3. SECRET_KEY, ACCESS_TOKEN_EXPIRE
4. Credenciales de superusuario (SUPERUSER_*) para semillas iniciales.
5. DOMAIN para definir cookies y URLs (domain_url, domain_auth_url).
6. Credenciales SMTP si deseas enviar correos (smtp_host, smtp_user, etc.).
7. Revisa también las variables propias del frontend (frontend/.env.local si aplica) como NEXT_PUBLIC_API_URL.

2. Servicios en Docker Compose

docker-compose.yml define seis contenedores:

Servicio	Imagen / Build	Puerto	Rol
db	postgres:16	5433→5432	Base de datos principal; inicializa con PGDATA separado y healthcheck pg_isready.
redis	redis:7	6379	Cache de sesiones (get_current_user) y backend de Huey (jobs:*). Se configura con appendonly yes.
backend	Build ./app/Dockerfile	expone 8000	FastAPI + Uvicorn. Monta ./app para desarrollo en caliente. Requiere db (healthy) y redis.
huey	Misma imagen del backend	—	Ejecuta huey_consumer.py apuntando a app.huey_task.huey. Necesita DB y Redis.
frontend	Build ./frontend/Dockerfile	expone 3000	Next.js con modo watch habilitado (WATCHPACK, CHOKIDAR). Monta el código y cachea node_modules.
nginx	nginx:1.27-alpine	80	Reverse proxy para frontend/backend. Config definido en nginx/nginx.conf. Útil para entornos locales integrados.

Cada servicio tiene límites de memoria (mem_limit, mem_reservation) para evitar que Docker Desktop se sature.

Levantar todo

docker compose up --build

La primera vez tarda un poco por instalación de dependencias. Usa -d si quieres correr en background.

3. Migraciones Alembic

1. Entra al contenedor backend:

docker compose run --rm backend alembic upgrade head

app/alembic/env.py lee settings.database_uri, así que no necesitas editar alembic.ini.

1. Generar nuevas migraciones:

docker compose run --rm backend alembic revision -m "descripcion"

Asegúrate de que todos los modelos estén importados en app/models/__init__.py para que Alembic detecte los cambios.

4. Datos iniciales

• Al iniciar FastAPI se ejecuta init_db(session) (app/scripts/init_db.py) vía lifespan, creando rol superuser, acceso ('*', '*') y la cuenta base si no existían.
• Si trabajas con entornos limpios, basta con levantar el backend una vez después de migrar.

5. Workers Huey

• El servicio huey del compose arranca automáticamente (huey_consumer.py app.huey_task.huey -w 2 -k thread).
• Si prefieres correrlo manualmente (por ejemplo en desarrollo con backend fuera de Docker):

GET-ChildItem app\huey_task.py # asegura el módulo en PYTHONPATH
poetry run huey_consumer.py app.huey_task.huey -w 2 -k thread

(ajusta según tu gestor de dependencias).

6. Tareas de mantenimiento

• Backups cifrados: Usa /api/admin/database (ver guía de usuario). Si lo haces desde CLI:

docker compose exec backend python -m app.utils.database_dump --help

(puedes crear un script adicional si lo requieres).

• Logs: Los archivos JSON se guardan en app/logs/app.json.log con rotación diaria. Monta el directorio en Docker o enrútalo a un volumen si quieres persistencia.

• Redis: Si necesitas limpiar locks o sesiones, puedes ejecutar:

docker compose exec redis redis-cli FLUSHDB

Hazlo sólo en desarrollo; en producción evita borrar trabajos en curso.

7. CI/CD sugerido

Aunque el repo no incluye pipelines listos, un flujo típico sería:

1. Ejecutar pruebas/lint (FastAPI + Next.js).
2. Construir imágenes backend y frontend.
3. Ejecutar alembic upgrade head contra la base de staging/producción.
4. Desplegar contenedores y reiniciar huey.
5. Verificar health endpoints (/api/docs, /api/openapi.json) y logs iniciales.

8. Troubleshooting

Síntoma	Posible causa	Acción
401 en todas las rutas	settings.domain distinto al host real; la cookie session_token no se envía	Ajusta DOMAIN en .env y reinicia backend/frontend.
Tablas vacías aun con datos	Cookie cfg:centros_costos inválida o centros dados de baja	Borrar preferencia (DELETE /api/admin/centros_costos/select) y seleccionar de nuevo.
Tarea Huey no corre	Lock atascado en Redis (jobs:lock:*)	Usa /api/admin/tasks/clean_lock/{task_id} o redis-cli DEL jobs:lock:....
Restauración “replace” falla	Falta extensión ltree	El wrapper _psql_load_data_with_triggers_off la crea automáticamente; revisa logs para confirmar permisos.
Migraciones no detectan cambios	Modelo no importado en app/models/__init__.py	Añade el modelo y vuelve a generar la revisión.

Con estos pasos puedes levantar un entorno completo, mantener migraciones y asegurar que los servicios acompañantes (Redis, Huey, Nginx) estén coordinados.