Zest — Manual del Usuario

1. Instalación

Requisitos

• • Docker y Docker Compose instalados en tu máquina
• • Aproximadamente 200 MB de espacio en disco (imagen + dependencias)
• • Cualquier hardware: Raspberry Pi 4, NAS, laptop antiguo, VM en la nube — cualquier cosa que ejecute Docker

Inicio rápido

git clone https://github.com/MartinSantosT/myzest.git
cd myzest
cp .env.example .env
docker compose up -d

Abre http://localhost:8000 en tu navegador. Eso es todo.

Asegurar tu instancia

1. Cambia la clave secreta — Abre .env y reemplaza el valor predeterminado:

   # Generate a secure key:
   python -c "import secrets; print(secrets.token_urlsafe(32))"

   Pega el resultado como ZEST_SECRET_KEY en tu archivo .env, luego reinicia:

   docker compose down && docker compose up -d

2. Cambia tu contraseña cuando quieras — ve a Configuración → Perfil dentro de la app. El primer usuario que se registra es el administrador y no hay credenciales compartidas o por defecto que rotar.

Puerto personalizado

Edita docker-compose.yml para cambiar el puerto:

ports:
  - "3000:8000"   # Access Zest on port 3000

Proxy inverso

Si estás exponiendo Zest a tu red local o a Internet, colócalo detrás de un proxy inverso (Nginx, Caddy, Traefik o Nginx Proxy Manager). Consulta el README para una configuración de Nginx de ejemplo.

2. Primeros pasos

Cuando iniques sesión por primera vez, Zest te muestra una breve experiencia de incorporación:

1. Bienvenida — Introducción a la filosofía de Zest
2. Tus recetas, tu historia — Cómo crear o importar tu primera receta
3. Recuerdos — Lo que hace diferente a Zest: conectar fotos y momentos con recetas

Puedes omitir la incorporación en cualquier momento, o hacer clic en "Crear mi primer recuerdo" para comenzar de inmediato.

El panel de control

Después de la incorporación, verás el panel de control principal con:

• • Cuadrícula de recetas — Todas tus recetas mostradas como tarjetas con fotos, calificaciones y tiempos estimados
• • Barra lateral (izquierda) — Navegación entre Recetas, ¿Qué cocino?, Lista de compras, Recetarios, Recuerdos y Configuración
• • Barra de búsqueda — Filtra recetas por texto, categoría, etiqueta o calificación
• • Botón + Nueva Receta — Crea una nueva receta desde cero

3. Recetas

Creando una receta

1. Haz clic en + Nueva Receta (o el botón naranja en la esquina superior derecha)
2. Completa los detalles:
   • ◦ Título (requerido)
   • ◦ Descripción — Una breve introducción o historia sobre el plato
   • ◦ Tiempo de preparación y cocción — En minutos
   • ◦ Porciones — Cuántas porciones hace la receta
   • ◦ Foto — Haz clic en el área de imagen para cargar una foto principal. Puedes agregar hasta 4 fotos en total (1 principal + 3 adicionales)
3. Ingredientes — Agrega uno por fila. Cada ingrediente tiene campos estructurados:
   • ◦ Cantidad (número)
   • ◦ Unidad (tazas, gramos, cucharada, etc.)
   • ◦ Nombre (el ingrediente en sí)
   • ◦ Nota (opcional: "finamente picado", "a temperatura ambiente")
4. Pasos — Agrega pasos de preparación en orden. Arrastra para reordenar si es necesario.
5. Categorías y etiquetas — Asigna categorías y etiquetas codificadas por color (ver sección 4)
6. Haz clic en Guardar

Editando una receta

Haz clic en cualquier tarjeta de receta para abrir su vista de detalles, luego haz clic en el botón Editar (lápiz). Todos los campos son editables. Los cambios se guardan cuando haces clic en Guardar.

Eliminando una receta

En la vista de detalles de la receta, haz clic en Eliminar (icono de papelera). Se te pedirá que confirmes. La eliminación elimina la receta, sus ingredientes, pasos, imágenes y cualquier entrada de recetario asociada. Los recuerdos vinculados se conservan pero su asociación con la receta se elimina.

Calificación y favoritos

• • Calificación — Haz clic en las estrellas (1–5) en cualquier tarjeta de receta o en la vista de detalles
• • Favoritos — Haz clic en el icono de corazón para marcar una receta como favorita. Usa el filtro de la barra lateral para ver solo favoritos.

Soporte para múltiples fotos

Cada receta admite hasta 4 fotos: una imagen principal (mostrada en la tarjeta) y 3 fotos adicionales visibles en la vista de detalles. Haz clic en el área "+" debajo de la imagen principal para agregar más fotos.

4. Categorías y etiquetas

Categorías

Las categorías son clasificaciones amplias para tus recetas (p. ej., "Mexicana", "Postres", "Sopas", "Comidas rápidas").

• • Agregar categorías — En el modal de receta, escribe en el campo de categoría. Si no existe, Zest la crea automáticamente.
• • Autocompletar — Mientras escribes, aparecen categorías coincidentes como sugerencias.
• • Una receta puede pertenecer a múltiples categorías.

Etiquetas

Las etiquetas son etiquetas flexibles y codificadas por color para preocupaciones transversales (p. ej., "Picante", "Apto para niños", "Cita nocturna", "Preparación de comidas").

• • Agregar etiquetas — En el modal de receta, selecciona etiquetas existentes o crea nuevas.
• • Colores personalizados — Cada etiqueta tiene un color. Haz clic en la muestra de color para cambiarlo.
• • Filtrado — Haz clic en cualquier etiqueta en la barra lateral o cuadrícula de recetas para filtrar por esa etiqueta. Se pueden combinar múltiples filtros.

5. Importar recetas desde URLs

Zest incluye un poderoso motor de extracción de 4 niveles que puede extraer recetas de prácticamente cualquier sitio web de cocina.

Cómo importar

1. Haz clic en la opción "Importar desde URL" en la barra lateral
2. Pega la URL de la página de la receta
3. Haz clic en Extraer
4. Zest muestra una vista previa con los datos extraídos: título, descripción, ingredientes, pasos, tiempos, porciones y foto
5. Revisa y edita cualquier cosa antes de guardar
6. Haz clic en Guardar para agregarla a tu colección

Cómo funciona el extractor

Zest intenta cuatro métodos en orden, utilizando el primero que funcione:

1. Biblioteca recipe-scrapers — Soporta más de 400 sitios de cocina populares con analizadores específicos del sitio
2. JSON-LD — Lee datos estructurados incrustados en la página (formato de receta Schema.org)
3. Microdata — Lee atributos de microdatos HTML
4. Análisis heurístico — Coincidencia inteligente de selectores CSS para páginas no estructuradas

Las recetas importadas se etiquetan automáticamente con la categoría "Importado de Internet" y una insignia azul que muestra el dominio de origen.

6. Ingredientes y calculadora de porciones

Ingredientes estructurados

Cada ingrediente tiene cuatro campos:

• • Cantidad — Un número (soporta decimales: 0.5, 1.25, etc.)
• • Unidad — La medida (tazas, gramos, ml, cucharada, cucharadita, oz, lb, etc.)
• • Nombre — El nombre del ingrediente
• • Nota — Detalles opcionales ("picado", "a temperatura ambiente", "opcional")

Calculadora de porciones

En cualquier vista de detalles de receta:

1. Busca el indicador de porciones (p. ej., "Sirve para 4")
2. Usa los botones + y − para ajustar el número de porciones
3. Todas las cantidades de ingredientes se recalculan proporcionalmente en tiempo real
4. Las fracciones se muestran hermosamente: ½, ⅓, ¼, ⅔, ¾

Por ejemplo, una receta para 4 porciones con "2 tazas de harina" escalada a 6 porciones muestra "3 tazas de harina".

7. ¿Qué cocino?

Esta es una de las características únicas de Zest. Responde a la pregunta: "Tengo pollo, arroz y cebolla — ¿qué puedo hacer?"

Cómo usar

1. Haz clic en "¿Qué cocino?" en la barra lateral
2. Comienza a escribir un nombre de ingrediente — aparecen sugerencias de tu base de datos de recetas
3. Haz clic para agregar ingredientes a tu lista
4. Zest muestra instantáneamente recetas coincidentes, clasificadas por porcentaje de coincidencia

Entendiendo los resultados

Cada resultado muestra:

• • Porcentaje de coincidencia — Cuántos de los ingredientes de la receta tienes (verde = 75%+, naranja = 50%+, gris = por debajo del 50%)
• • Ingredientes que faltan — Destacados en rojo para que sepas qué necesitarías comprar
• • Ajuste de porciones — Escala la receta directamente desde los resultados
• • "Agregar a la lista de compras" — Un clic para agregar los ingredientes que faltan a tu lista de compras

8. Lista de compras

Agregando artículos

Hay varias formas de agregar artículos a tu lista de compras:

• • Desde cualquier vista de detalles de receta, haz clic en "Agregar a la lista de compras"
• • Desde los resultados de "¿Qué cocino?", haz clic en "Agregar artículos que faltan"
• • Escribe manualmente artículos en la vista de lista de compras

Combinación inteligente

Cuando agregas ingredientes de múltiples recetas, Zest los combina inteligentemente. Si la Receta A necesita 200g de arroz y la Receta B necesita 100g de arroz, tu lista de compras muestra 300g de arroz.

Usando la lista

• • Marca artículos mientras compras
• • La lista persiste entre sesiones
• • Borra artículos completados o la lista completa cuando hayas terminado

9. Recuerdos

Los recuerdos son lo que hace diferente a Zest de cualquier otro gestor de recetas. Un recuerdo conecta fotos, fechas, ubicaciones e historias con una receta, convirtiendo tu colección de recetas en un diario culinario.

Creando un recuerdo

1. Haz clic en Recuerdos en la barra lateral
2. Haz clic en + Nuevo Recuerdo
3. Completa los detalles:
   • ◦ Título — "Cena de Navidad 2025", "Primer intento de masa madre", etc.
   • ◦ Fotos — Carga hasta 10 fotos. Las fotos JPEG con datos EXIF completarán automáticamente la fecha y ubicación.
   • ◦ Fecha — Cuándo sucedió (detectado automáticamente del EXIF de la foto si está disponible)
   • ◦ Ubicación — Dónde sucedió (detectado automáticamente de coordenadas GPS mediante codificación inversa)
   • ◦ Historia — La descripción de lo que pasó, quién estuvo allí, por qué fue especial
   • ◦ Receta vinculada — Asocia este recuerdo con una receta de tu colección
4. Haz clic en Guardar

Características de fotos

• • Carga de múltiples fotos — Selecciona múltiples fotos a la vez
• • Detección automática de EXIF — Zest lee automáticamente la fecha y coordenadas GPS de fotos JPEG
• • Codificación inversa — Las coordenadas GPS se convierten en nombres de lugares legibles (p. ej., "Brooklyn, Nueva York")
• • Soporte HEIC/HEIF — Las fotos del iPhone funcionan de inmediato
• • Optimización de imágenes — Las fotos se redimensionan automáticamente (máx. 1920px) y se convierten a JPEG para un almacenamiento óptimo

Viendo recuerdos

• • Vista de cuadrícula — Todos los recuerdos mostrados como tarjetas con foto de portada, fecha, ubicación y receta vinculada
• • Vista de detalles — Haz clic en cualquier recuerdo para ver la galería de fotos completa, historia y metadatos
• • Desde la vista de receta — Cada receta muestra sus recuerdos asociados en una sección dedicada

Editando y eliminando

• • Haz clic en el botón Editar en la vista de detalles del recuerdo para modificar cualquier campo o agregar/eliminar fotos
• • Haz clic en Eliminar para eliminar permanentemente el recuerdo y sus fotos

10. Tarjetas de momento

Las tarjetas de momento convierten tus recuerdos en imágenes hermosas y compartibles diseñadas para redes sociales.

Generando una tarjeta

1. Abre cualquier recuerdo que tenga al menos una foto
2. Haz clic en el botón Compartir (botón naranja degradado)
3. Elige una plantilla:
   • ◦ Historia (1080×1920) — Historias de Instagram, TikTok
   • ◦ Cuadrado (1080×1080) — Feed de Instagram, WhatsApp
   • ◦ Horizontal (1200×630) — Facebook, Twitter/X
4. La vista previa se actualiza en tiempo real
5. Haz clic en Descargar o usa el botón Compartir (en móvil, usa la hoja de intercambio nativa)

Diseño de tarjeta

Cada tarjeta incluye:

• • Tu foto como fondo de sangrado completo con superposición de gradiente oscuro
• • El título del recuerdo en texto grande y audaz
• • Fecha y ubicación
• • Nombre de la receta vinculada
• • Marca Zest sutil (barra naranja + texto "Zest")

11. Recetarios

Los recetarios son colecciones curadas de recetas — perfectas para organizar por tema, compartir con amigos o crear exportaciones PDF dignas de regalo.

Creando un recetario

1. Haz clic en Recetarios en la barra lateral
2. Haz clic en + Nuevo Recetario
3. Agrega un nombre, descripción y opcionalmente una nota del autor
4. Fotos de portada — Carga hasta 2 imágenes de portada. Usa arrastrar para reposicionar para enmarcar perfectamente.
5. Agregar recetas — Selecciona recetas de tu colección para incluir
6. Haz clic en Guardar

Administrando recetarios

• • Reordenar recetas — Arrastra recetas dentro de un recetario para establecer el orden
• • Editar — Cambia nombre, descripción, portadas o selección de recetas en cualquier momento
• • Eliminar — Elimina el recetario pero no las recetas mismas

Nota del autor

Cada recetario tiene una nota personal opcional que aparece en la parte superior cuando se comparte o se exporta. Úsala para dedicatorias, contexto o un mensaje personal ("Mamá, aquí están nuestras recetas familiares que he estado recopilando...").

12. Compartir

Enlaces de compartición pública

1. Abre un recetario
2. Haz clic en Compartir
3. Zest genera un enlace único y público (p. ej., http://yourserver/shared/abc123)
4. Cualquiera con el enlace puede ver el recetario y todas sus recetas — sin necesidad de cuenta
5. Puedes revocar el enlace en cualquier momento

Lo que ven los destinatarios

La vista compartida es una presentación hermosa y de solo lectura de tu recetario con fotos de portada, tarjetas de receta y detalles completos de la receta (ingredientes, pasos, fotos). Tu nota del autor se muestra en la parte superior.

13. Exportar PDF

Exporta recetarios como PDF profesionales adecuados para imprimir o regalar.

Cómo exportar

1. Abre un recetario
2. Haz clic en el botón PDF
3. Zest genera un PDF con:
   • ◦ Página de portada con el nombre del recetario y fecha
   • ◦ Tarjetas de receta con ingredientes, pasos y metadatos
   • ◦ Tipografía adecuada con fuentes DejaVu (soporte Unicode completo)
4. El PDF se descarga automáticamente

14. Configuración y perfil

Accede a la configuración haciendo clic en tu avatar o el icono de engranaje en la barra lateral.

Perfil

• • Nombre — Tu nombre para mostrar
• • Correo electrónico — Tu correo electrónico de inicio de sesión
• • Contraseña — Cambia tu contraseña (requiere contraseña actual)
• • Avatar — Carga una foto de perfil

Categorías y etiquetas

• • Ver, renombrar o eliminar categorías
• • Ver, renombrar, cambiar color o eliminar etiquetas

15. Respaldos y datos

Respaldos automáticos

1. Ve a Configuración → Respaldos
2. Habilita los respaldos automáticos
3. Configura:
   • ◦ Frecuencia — Cada 12 horas, 24 horas o 7 días
   • ◦ Retención — Cuántos respaldos mantener (predeterminado: 7)
   • ◦ Incluir imágenes — Si incluir fotos cargadas en respaldos

Los respaldos se almacenan en el directorio ./data/backups/ en tu máquina host.

Exportación manual

• • Respaldo completo (ZIP) — Exporta la base de datos completa + todas las imágenes. Úsalo para recuperación ante desastres o migración a un nuevo servidor.
• • Exportación JSON — Exporta recetas en un formato JSON portátil para interoperabilidad.

Importar

• • Importación de base de datos — Carga un ZIP de respaldo completo para restaurar toda tu instancia. Advertencia: esto reemplaza completamente la base de datos actual.
• • Importación JSON — Carga un archivo JSON para agregar recetas a tu colección existente. Los duplicados se detectan y se omiten.

Migración entre servidores

1. Exporta un respaldo completo del servidor antiguo
2. Configura una instancia de Zest nueva en el nuevo servidor
3. Importa el respaldo
4. Listo — todas tus recetas, recuerdos, recetarios e imágenes se restauran

16. Modo oscuro

Haz clic en el icono de luna/sol en el encabezado de la barra lateral para cambiar entre temas claro y oscuro. Tu preferencia se guarda localmente y persiste entre sesiones.

17. Atajos de teclado

18. Solución de problemas

"El puerto 8000 ya está en uso"

Cambia el puerto en docker-compose.yml:

ports:
  - "9000:8000"

En Windows, los puertos 7681–8782 pueden ser bloqueados por Hyper-V. Usa el puerto 9000 o superior.

Las fotos no se cargan

• • Verifica que el directorio ./app/static/uploads exista y sea escribible
• • El tamaño máximo de archivo depende de la configuración de tu proxy inverso. Agrega client_max_body_size 20M; a tu configuración de Nginx.

Migraciones de base de datos

Las migraciones corren automáticamente cada vez que arranca el contenedor. No hay un comando manual que ejecutar. La rutina de arranque crea las tablas faltantes y agrega columnas faltantes en bases de datos existentes. El trabajo de esquema es idempotente — reiniciar una base de datos al día es no-op.

Si ves errores de arranque que mencionan el esquema, comparte el log del contenedor al abrir un issue:

docker compose logs -f zest

Las fotos HEIC no funcionan

El soporte HEIC requiere el paquete pillow-heif, que está incluido en la imagen Docker predeterminada. Si ejecutas Zest fuera de Docker, instálalo por separado:

pip install pillow-heif

Olvidé tu contraseña

Si está bloqueado, puedes restablecer a través de la base de datos:

docker exec -it zest python -c "
import bcrypt
from app.database import SessionLocal
from app.models import User
db = SessionLocal()
user = db.query(User).filter(User.email == 'your@email.com').first()
user.password_hash = bcrypt.hashpw(b'newpassword', bcrypt.gensalt()).decode()
db.commit()
print('Password reset successfully')
"

Verificación de salud

Verifica que tu instancia esté funcionando:

curl http://localhost:8000/api/health
# {"status": "healthy", "recipes": 42, "users": 1}

Usa este punto final con Uptime Kuma, Healthchecks.io o cualquier herramienta de monitoreo.