Saltar a contenido

Empezar

Este tutorial te guía para levantar todo el stack de Camarero-IA en local: backend (FastAPI), frontend (Next.js) y la base de datos PostgreSQL en contenedores Podman/Docker.

Camarero-IA es un sistema de pedidos por QR para bares y restaurantes con recomendaciones personalizadas mediante IA. Al final de este tutorial tendrás el sistema corriendo y accesible desde el navegador.

Sobre los contenedores

El proyecto usa ficheros docker-compose. Los comandos docker compose ... funcionan igual con podman compose ... si usas Podman. En este tutorial se muestran con docker compose.

Arquitectura del repositorio

El repositorio organiza el código con Git submodules:

Directorio Descripción
frontend/ Next.js 16 + React 19 + TypeScript + Tailwind CSS 4 (submodule)
backend/ FastAPI + PostgreSQL + NVIDIA NIM (submodule)
docs/ Documentación del sistema
scripts/ Scripts de deploy y seeding
nginx/ Configuración de nginx

Stack tecnológico

Componente Tecnología
Frontend Next.js 16, React 19, TypeScript, Tailwind CSS 4
Backend FastAPI, Python 3.12, SQLAlchemy 2.0 (async)
Base de datos PostgreSQL 15
IA NVIDIA NIM
Despliegue Docker / Podman, nginx

Prerequisitos

Necesitas instalado en tu máquina:

  • Git (con soporte de submódulos).
  • Docker o Podman (con docker compose / podman compose) para la base de datos y los contenedores.
  • Python 3.12+ (si vas a correr el backend fuera de contenedor).
  • Node.js 20+ (para el frontend y los builds con Podman).

Además, para activar todas las funcionalidades:

  • Una NVIDIA_API_KEY (NVIDIA NIM) para las recomendaciones y el chat con IA.
  • Credenciales Google OAuth (cliente y admin) si quieres probar el login.

Sin claves de IA

Puedes levantar el stack sin NVIDIA_API_KEY ni credenciales OAuth para inspeccionar la API y la BD; solo las funciones que dependen de esos servicios quedarán inactivas.

Paso 1 — Clonar el repositorio con submódulos

# Clonar con submódulos en un solo paso
git clone --recurse-submodules <URL_DEL_REPO> camarero-ia
cd camarero-ia

Si ya lo clonaste sin submódulos, inicialízalos:

git submodule init
git submodule update

Paso 2 — Configurar variables de entorno

El backend lee su configuración de un fichero .env. Copia la plantilla y edítala:

cp backend/.env.example backend/.env

Variables relevantes (ver backend/.env.example):

Variable Descripción
DATABASE_URL Cadena de conexión PostgreSQL (postgresql+asyncpg://...)
SECRET_KEY Clave secreta para firmar tokens JWT
NVIDIA_API_KEY Clave de NVIDIA NIM para recomendaciones y chat IA
GOOGLE_CUSTOMER_CLIENT_ID / GOOGLE_CUSTOMER_CLIENT_SECRET OAuth de clientes
GOOGLE_ADMIN_CLIENT_ID / GOOGLE_ADMIN_CLIENT_SECRET OAuth de administradores
ADMIN_SUPER_EMAIL Email del superadmin a crear en el bootstrap inicial

DATABASE_URL y contenedores

En docker-compose.dev.yml la variable DATABASE_URL se inyecta apuntando al host del contenedor de la BD (camarero_ia_db), no a localhost. Si corres el backend dentro de Compose no necesitas tocarla; si lo corres a mano (Opción B), usa localhost como host.

Paso 3 — Levantar el stack

Hay dos formas de trabajar en local.

Opción A — Todo con Compose (recomendada)

El script scripts/dev.sh arranca el entorno de desarrollo con recarga en vivo usando backend/docker-compose.dev.yml. Levanta la base de datos PostgreSQL y el backend juntos:

./scripts/dev.sh

El script:

  1. Comprueba que existe backend/.env (si no, copia .env.example y te pide editarlo).
  2. Detiene contenedores previos.
  3. Construye y arranca el entorno en modo desarrollo (docker compose -f docker-compose.dev.yml up --build).

Servicios y puertos del entorno de desarrollo:

Servicio Contenedor Puerto
PostgreSQL camarero_ia_db 5432 (configurable con POSTGRES_PORT)
Backend (FastAPI) camarero_ia_backend 8000 (configurable con BACKEND_PORT)

Alternativa con make

Desde la raíz del repo existen atajos en el Makefile: make dev (desarrollo), make local (solo backend), make stop, make logs y make clean. Internamente delegan en deploy.sh.

Opción B — Backend en local + BD en contenedor

Si prefieres ejecutar el backend directamente con Python (más rápido para iterar), levanta solo la base de datos en contenedor y corre el backend en un entorno virtual.

  1. Arranca únicamente PostgreSQL:

    docker compose -f backend/docker-compose.dev.yml up camarero_ia_db

  2. Crea el entorno virtual e instala dependencias del backend:

    cd backend
python -m venv venv
source venv/bin/activate    # Windows: venv\Scripts\activate
pip install -r requirements.txt

  3. Arranca el servidor con recarga:

    uvicorn app.main:app --reload

    Ajusta DATABASE_URL

    Con el backend fuera del contenedor, en backend/.env el host de DATABASE_URL debe ser localhost (la BD expone el puerto 5432 en tu máquina).

Paso 4 — Levantar el frontend

El frontend (Next.js) vive en frontend/. Instala dependencias y arráncalo:

cd frontend
npm install
npm run dev

Por defecto el frontend queda en http://localhost:3000 y espera la API en http://localhost:8000.

Paso 5 — Verificar

Con el stack levantado:

Comprueba el estado de los contenedores y los logs:

# Estado de los servicios
docker compose -f backend/docker-compose.dev.yml ps

# Logs en tiempo real
docker compose -f backend/docker-compose.dev.yml logs -f

Datos de ejemplo (seed)

El directorio scripts/ incluye scripts de seeding (p.ej. scripts/seed_amici.py) para poblar la base de datos con un restaurante, menú y datos de demostración.

Resolución de problemas

  • backend/.env not found: ejecuta de nuevo ./scripts/dev.sh; copiará la plantilla. Edita el fichero y vuelve a lanzarlo.
  • El backend no conecta con la BD: revisa el host de DATABASE_URL (contenedor camarero_ia_db en Compose, localhost en local) y que el contenedor de PostgreSQL esté healthy.
  • Puerto ocupado: cambia BACKEND_PORT o POSTGRES_PORT en backend/.env.

Siguientes pasos

  • Instalación de entrega — puesta en marcha paso a paso desde cero (migraciones, seed, OAuth, URLs).
  • Backend — estructura, arquitectura hexagonal, modelos, servicios y tests.
  • Frontend — aplicación Next.js, sincronización en tiempo real (SSE) y UI.
  • Variables de entorno — referencia exhaustiva.
  • Base de datos — motor, migraciones y seed Amici.