Saltar a contenido

Instalación de entrega (paso a paso)

Guía de puesta en marcha completa del stack de Camarero IA desde cero: backend (FastAPI), frontend (Next.js) y PostgreSQL. Es el camino recomendado para una entrega / demo en una máquina limpia.

Para el tutorial general con las dos opciones de arranque (Compose o backend manual), ver Empezar. Para el detalle por pieza, ver Backend en local y Frontend en local.

Sin valores secretos

Esta guía usa solo placeholders (p. ej. tu-clave-aqui). Genera tus propias claves; nunca copies credenciales de otros entornos.

Requisitos

Requisito Versión / nota
Git (con submódulos) git clone --recurse-submodules
Docker o Podman (con compose) docker compose o podman compose
Python 3.12+ (solo si corres el backend fuera de contenedor)
Node.js 20.x LTS (frontend)
openssl Para generar SECRET_KEY

Opcionales según las funciones que quieras probar:

  • NVIDIA_API_KEY — chat con IA y recomendaciones (sin ella, la API y la BD funcionan; solo las funciones IA quedan inactivas).
  • Credenciales Google/Apple OAuth — login de cliente y admin (ver Configuración OAuth).

1. Clonar el repositorio

git clone --recurse-submodules <URL_DEL_REPO> camarero-ia
cd camarero-ia

Si ya lo clonaste sin submódulos:

git submodule init
git submodule update

2. Configurar el .env del backend

cp backend/.env.example backend/.env

Edita backend/.env como mínimo con:

DATABASE_URL=postgresql+asyncpg://camarero_user:camarero_password@localhost:5432/camarero_db
SECRET_KEY=[GENERA-CON-openssl-rand-hex-32]
DEBUG=false

openssl rand -hex 32   # genera una SECRET_KEY válida (mín. 32 caracteres)

SECRET_KEY es obligatoria

La aplicación no arranca sin una SECRET_KEY de al menos 32 caracteres (se valida en todos los entornos). Ver la referencia de variables.

El resto de variables (IA, OAuth, CORS) pueden quedar vacías para una primera arrancada; se documentan en la referencia exhaustiva de variables.

3. Levantar BD + backend con scripts/dev.sh

Desde la raíz del repo:

./scripts/dev.sh

El script hace tres cosas, en orden:

  1. Comprueba que existe backend/.env; si no, copia backend/.env.example y sale pidiendo que lo edites antes de continuar.
  2. Detiene contenedores previos (docker compose -f docker-compose.dev.yml down).
  3. Construye y arranca backend/docker-compose.dev.yml con recarga en vivo (up --build; acepta argumentos extra que se pasan a up).

Servicios que levanta (backend/docker-compose.dev.yml):

Servicio Contenedor Puerto local Notas
PostgreSQL 15 (postgres:15-alpine) camarero_ia_db 5432 (POSTGRES_PORT) Volumen camarero_ia_postgres_data; healthcheck pg_isready
Backend FastAPI camarero_ia_backend 8000 (BACKEND_PORT) Build de Dockerfile.dev; monta .:/app con live reload

Dentro de Compose el backend no usa el DATABASE_URL de tu .env tal cual: el fichero compose inyecta DATABASE_URL apuntando al host camarero_ia_db (no localhost), con usuario/BD tomados de POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB (por defecto camarero_user / camarero_password / camarero_db).

¿Podman en vez de Docker?

scripts/dev.sh invoca docker compose. Con Podman, o bien defines un alias, o levantas la BD a mano y corres el backend local (ver Backend en local).

4. Aplicar migraciones y seed

4.1. Migraciones (alembic upgrade head)

Con la BD levantada, aplica el esquema desde backend/ con el venv:

cd backend
python3.12 -m venv venv
venv/bin/pip install -r requirements.txt
venv/bin/alembic upgrade head

Verifica que la cadena está sana (debe haber un solo head):

venv/bin/alembic current   # revisión aplicada
venv/bin/alembic heads     # debe devolver UNA sola revisión

BD vacía

Sobre una base de datos vacía, alembic/env.py crea el esquema canónico actual con Base.metadata.create_all() y hace stamp a head; las BD ya existentes siguen el camino incremental normal. Detalle en Migraciones de BD y Base de datos.

4.2. Seed del restaurante demo (Amici)

El script scripts/seed_amici.py puebla un restaurante completo: restaurante, menú, categorías, productos (con enriquecimiento IA), extras, grupos de opciones, promociones, salas, mesas y base de conocimiento. Es re-ejecutable: borra el restaurant_id elegido y lo vuelve a sembrar.

# Amici Madrid en id=1 (por defecto)
DATABASE_URL=postgresql://camarero_user:camarero_password@localhost:5432/camarero_db \
  python3 scripts/seed_amici.py

# Segunda instancia (p. ej. Bilbao en id=5)
DATABASE_URL=postgresql://camarero_user:camarero_password@localhost:5432/camarero_db \
  python3 scripts/seed_amici.py --restaurant-id 5 --name "Amici Bilbao"

Qué carga y con qué flags se controla se detalla en Base de datos.

5. Arrancar el frontend

cd frontend
npm install
cp .env.example .env   # en local basta con los valores por defecto
npm run dev

En local no necesitas tocar nada: por defecto el frontend apunta a http://localhost:8000/api/v1 (ver Frontend en local). El dev server eleva el heap de Node (--max-old-space-size=3072); arráncalo siempre con npm run dev, no con next dev directamente.

6. (Opcional) Configurar OAuth

El script scripts/setup_oauth.sh escribe en backend/.env:

  • GOOGLE_CUSTOMER_CLIENT_ID / GOOGLE_CUSTOMER_CLIENT_SECRET y sus equivalentes de admin,
  • CUSTOMER_REDIRECT_URI y ADMIN_REDIRECT_URI para el dominio de producción,
  • genera SECRET_KEY si falta y fija DEBUG=false.

Necesitas tus propios credenciales de Google Cloud Console (client ID + client secret) y registrar en ellas las URIs de redirección (<tu-dominio>/auth/callback y <tu-dominio>/admin/auth/callback). Tras ejecutarlo, reinicia el backend.

Revisa el script antes de ejecutarlo

setup_oauth.sh contiene valores de ejemplo y rutas de máquina hardcodeadas. Léelo y adapta dominio y rutas a tu entorno; nunca publiques tu .env resultante.

7. Verificar la instalación

Qué URL local
Frontend http://localhost:3000
API (Swagger UI) http://localhost:8000/docs
API (ReDoc) http://localhost:8000/redoc
API base http://localhost:8000/api/v1

Estado de los contenedores y logs:

docker compose -f backend/docker-compose.dev.yml ps
docker compose -f backend/docker-compose.dev.yml logs -f

Site demo de referencia (histórico — servidor dado de baja, no se transmite):

  • Web: https://camarero-demo.n0idea.app (no operativa)
  • API: https://api.camarero-demo.n0idea.app/api/v1 (no operativa)

Para un despliegue nuevo, sigue los pasos de esta guía (Docker/Compose + migraciones + seed) y provisiona infraestructura propia.

Resolución de problemas

  • backend/.env not found: re-ejecuta ./scripts/dev.sh; copiará la plantilla. Edítala y vuelve a lanzarlo.
  • El backend no conecta con la BD: dentro de Compose el host debe ser camarero_ia_db; con backend manual, localhost. Comprueba que el contenedor de Postgres esté healthy (pg_isready).
  • El backend no arranca (error SECRET_KEY): genera una clave de 32+ caracteres con openssl rand -hex 32.
  • Puerto ocupado: ajusta BACKEND_PORT o POSTGRES_PORT (los lee backend/docker-compose.dev.yml).
  • El chat falla por timeout: necesita el LLM (variables NVIDIA_* o proxy local en :4800). Ver Backend en local.

Páginas relacionadas