docs: add complete README with installation guide
This commit is contained in:
consultoria-as
282
README.md
Normal file
282
README.md
Normal file
@@ -0,0 +1,282 @@
|
||||
# 🍽️ Cocina con Alma
|
||||
|
||||
Gestor de recetas y menú semanal público para negocios de comida / viandas.
|
||||
|
||||
Combina **Tandoor Recipes** (gestión interna de recetas, inventario y planificación) con una **página pública** donde los clientes pueden ver el menú de la semana desde sus celulares.
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Arquitectura
|
||||
|
||||
| Servicio | Puerto | Descripción |
|
||||
|----------|--------|-------------|
|
||||
| **Tandoor Recipes** | `8080` | Panel de administración para recetas, ingredientes, inventario y meal plan |
|
||||
| **Menú Público** | `80` | Página web responsive con el menú semanal para clientes |
|
||||
| **PostgreSQL** | — | Base de datos persistente para Tandoor |
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ Clientes │ │ Tu madre │ │ PostgreSQL │
|
||||
│ (navegador) │ │ (navegador) │ │ (datos) │
|
||||
│ │ │ │ │ │
|
||||
│ Puerto 80 │ │ Puerto 8080 │ │ Puerto 5432 │
|
||||
│ Menú público │ │ Tandoor Admin │ │ (interno) │
|
||||
└────────┬────────┘ └────────┬────────┘ └─────────────────┘
|
||||
│ │
|
||||
└────────┬───────────────┘
|
||||
│
|
||||
┌────────┴────────┐
|
||||
│ Docker Compose │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Requisitos
|
||||
|
||||
- [Docker](https://docs.docker.com/get-docker/)
|
||||
- [Docker Compose](https://docs.docker.com/compose/)
|
||||
- 2 GB de RAM mínimo
|
||||
- 5 GB de disco disponible
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Instalación paso a paso
|
||||
|
||||
### 1. Clonar el repositorio
|
||||
|
||||
```bash
|
||||
git clone https://git.consultoria-as.com/consultoria-as/cocina-con-alma.git
|
||||
cd cocina-con-alma
|
||||
```
|
||||
|
||||
### 2. Configurar variables de entorno
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
nano .env # o vim
|
||||
```
|
||||
|
||||
Editá al menos estas variables:
|
||||
|
||||
```env
|
||||
SECRET_KEY=una_clave_larga_y_aleatoria_de_50_caracteres
|
||||
POSTGRES_PASSWORD=contraseña_segura_para_postgres
|
||||
TANDOOR_API_TOKEN=dejar_vacio_por_ahora
|
||||
```
|
||||
|
||||
> 💡 Para generar `SECRET_KEY`:
|
||||
> ```bash
|
||||
> openssl rand -hex 32
|
||||
> ```
|
||||
|
||||
### 3. Levantar los servicios por primera vez
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
La primera vez tarda varios minutos porque descarga imágenes y Tandoor ejecuta migraciones.
|
||||
|
||||
### 4. Crear el usuario administrador
|
||||
|
||||
```bash
|
||||
docker exec -i cocinaconalma-web_recipes-1 \
|
||||
/opt/recipes/venv/bin/python manage.py shell << 'EOF'
|
||||
from django.contrib.auth import get_user_model
|
||||
User = get_user_model()
|
||||
user = User.objects.create_superuser(
|
||||
"admin", "admin@cocina.com", "Alma2024!"
|
||||
)
|
||||
print("Usuario creado:", user.username)
|
||||
EOF
|
||||
```
|
||||
|
||||
### 5. Crear el espacio de trabajo (space) y obtener token de API
|
||||
|
||||
```bash
|
||||
# Crear space y asignar grupo admin
|
||||
docker exec -i cocinaconalma-web_recipes-1 \
|
||||
/opt/recipes/venv/bin/python manage.py shell << 'EOF'
|
||||
from cookbook.models import Space, UserSpace
|
||||
from django.contrib.auth.models import Group
|
||||
from django.contrib.auth import get_user_model
|
||||
|
||||
User = get_user_model()
|
||||
user = User.objects.get(username="admin")
|
||||
|
||||
space = Space.objects.create(name="Cocina con Alma", created_by=user)
|
||||
us = UserSpace.objects.create(user=user, space=space)
|
||||
us.groups.add(Group.objects.get(name='admin'))
|
||||
us.save()
|
||||
|
||||
user.userspace_active = us
|
||||
user.save()
|
||||
|
||||
# Crear token de API para el menú público
|
||||
from rest_framework.authtoken.models import Token
|
||||
token, _ = Token.objects.get_or_create(user=user)
|
||||
print(f"TANDOOR_API_TOKEN={token.key}")
|
||||
EOF
|
||||
```
|
||||
|
||||
Copiá el token impreso y pegalo en tu archivo `.env`:
|
||||
|
||||
```env
|
||||
TANDOOR_API_TOKEN=el_token_que_te_dio_el_comando_anterior
|
||||
```
|
||||
|
||||
### 6. Recrear el contenedor del menú público para que lea el token
|
||||
|
||||
```bash
|
||||
docker compose up -d --force-recreate menu_publico
|
||||
```
|
||||
|
||||
### 7. Acceder
|
||||
|
||||
| Uso | URL |
|
||||
|-----|-----|
|
||||
| Panel de administración (Tandoor) | `http://IP_DEL_SERVIDOR:8080` |
|
||||
| Menú público para clientes | `http://IP_DEL_SERVIDOR` |
|
||||
|
||||
**Credenciales por defecto:**
|
||||
- Usuario: `admin`
|
||||
- Contraseña: `Alma2024!` (cambiarla en producción)
|
||||
|
||||
---
|
||||
|
||||
## 📝 Uso diario
|
||||
|
||||
### Para tu madre (panel de Tandoor)
|
||||
|
||||
1. Entrar a `http://IP:8080` e iniciar sesión
|
||||
2. **Recetas** → Crear o importar recetas nuevas
|
||||
3. **Plan** (calendario) → Arrastrar recetas a los días de la semana
|
||||
4. **Foods** → Registrar ingredientes y precios para control de stock
|
||||
5. **Shopping** → Generar lista de compras automática desde el meal plan
|
||||
|
||||
### Para los clientes
|
||||
|
||||
Simplemente acceden a `http://IP_DEL_SERVIDOR` y ven el menú de los próximos 7 días. No necesitan iniciar sesión.
|
||||
|
||||
---
|
||||
|
||||
## 🗄️ Acceso directo a la base de datos
|
||||
|
||||
```bash
|
||||
# Entrar a PostgreSQL
|
||||
docker exec -it cocinaconalma-db_recipes-1 \
|
||||
psql -U djangouser -d djangodb
|
||||
|
||||
# Consultas útiles
|
||||
\dt # listar tablas
|
||||
SELECT * FROM cookbook_recipe; # ver recetas
|
||||
SELECT * FROM cookbook_food; # ver ingredientes
|
||||
SELECT * FROM cookbook_mealplan; # ver menú semanal
|
||||
\q # salir
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Archivos modificados de Tandoor
|
||||
|
||||
Este proyecto usa la imagen oficial de Tandoor pero monta dos archivos modificados:
|
||||
|
||||
| Archivo | Cambio |
|
||||
|---------|--------|
|
||||
| `tandoor/settings.py` | Agrega `TokenAuthentication` de DRF para que la app Flask se conecte vía API |
|
||||
| `tandoor/scope_middleware.py` | Extiende el middleware de espacios para que también funcione con tokens de API |
|
||||
|
||||
Estos cambios son necesarios porque Tandoor, por defecto, solo expone la API REST para sesiones web y OAuth2. La app Flask necesita un token fijo para leer el menú semanal sin intervención humana.
|
||||
|
||||
---
|
||||
|
||||
## 📁 Estructura del proyecto
|
||||
|
||||
```
|
||||
cocina-con-alma/
|
||||
├── docker-compose.yml # Orquestación de servicios
|
||||
├── .env # Variables de entorno (NO subir a git)
|
||||
├── .env.example # Plantilla de variables
|
||||
├── .gitignore
|
||||
├── README.md # Este archivo
|
||||
├── menu-publico/ # App Flask - menú público
|
||||
│ ├── Dockerfile
|
||||
│ ├── requirements.txt
|
||||
│ ├── app.py # Lógica de conexión a Tandoor
|
||||
│ └── templates/
|
||||
│ └── index.html # Página del menú semanal
|
||||
└── tandoor/ # Parches a Tandoor
|
||||
├── settings.py
|
||||
└── scope_middleware.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Notas de seguridad
|
||||
|
||||
- **Nunca commitear el archivo `.env`** (ya está en `.gitignore`)
|
||||
- Cambiar la contraseña por defecto de `admin` después de la primera instalación
|
||||
- El token de API tiene acceso de lectura a todo Tandoor. No exponerlo públicamente
|
||||
- Para producción, considerar:
|
||||
- HTTPS (usar reverse proxy como Nginx o Traefik)
|
||||
- Firewall: solo exponer puertos 80 y 8080 si es necesario
|
||||
- Backups automáticos de `tandoor/postgresql/`
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Backup y restauración
|
||||
|
||||
### Backup
|
||||
|
||||
```bash
|
||||
# Backup de la base de datos
|
||||
docker exec cocinaconalma-db_recipes-1 pg_dump -U djangouser djangodb > backup_$(date +%Y%m%d).sql
|
||||
|
||||
# Backup de archivos subidos (imágenes de recetas)
|
||||
docker cp cocinaconalma-web_recipes-1:/opt/recipes/mediafiles ./mediafiles_backup
|
||||
```
|
||||
|
||||
### Restauración
|
||||
|
||||
```bash
|
||||
# Restaurar base de datos
|
||||
docker exec -i cocinaconalma-db_recipes-1 psql -U djangouser -d djangodb < backup_20240101.sql
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Solución de problemas
|
||||
|
||||
### El menú público muestra "Error de API"
|
||||
|
||||
1. Verificar que `TANDOOR_API_TOKEN` esté configurado en `.env`
|
||||
2. Recrear el contenedor: `docker compose up -d --force-recreate menu_publico`
|
||||
3. Revisar logs: `docker logs cocinaconalma-menu_publico-1`
|
||||
|
||||
### Tandoor no responde en el puerto 8080
|
||||
|
||||
```bash
|
||||
docker logs cocinaconalma-web_recipes-1 --tail 50
|
||||
```
|
||||
|
||||
Esperar a que aparezca "Booting worker" — la primera vez tarda.
|
||||
|
||||
### Olvidé la contraseña de admin
|
||||
|
||||
```bash
|
||||
docker exec -it cocinaconalma-web_recipes-1 \
|
||||
/opt/recipes/venv/bin/python manage.py changepassword admin
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📄 Licencia
|
||||
|
||||
Este proyecto integra software de terceros:
|
||||
- [Tandoor Recipes](https://github.com/TandoorRecipes/recipes) — MIT License
|
||||
- Las recetas de ejemplo son ilustrativas.
|
||||
|
||||
---
|
||||
|
||||
**Desarrollado para el negocio de viandas de mamá** ❤️
|
||||
Reference in New Issue
Block a user