SuiteCoffee — Sistema de gestión para cafeterías (Dockerizado y multi‑servicio)

SuiteCoffee es un sistema modular pensado para la gestión de cafeterías (y negocios afines), con servicios Node.js para aplicación y Authentik autenticación, bases de datos PostgreSQL separadas para negocio y multi‑tenencia, y un stack Docker Compose que facilita levantar entornos de desarrollo y producción. Incluye herramientas auxiliares como Nginx Proxy Manager (NPM) y CloudBeaver para administrar bases de datos desde el navegador.

Repositorio: https://gitea.mateosaldain.uy/msaldain/SuiteCoffee.git

---

Tabla de contenidos

• Arquitectura
• Características principales
• Requisitos
• Inicio rápido
• Variables de entorno
• Endpoints
• Estructura del proyecto
• Herramientas auxiliares (NPM y CloudBeaver)
• Backups y restauración de volúmenes
• Comandos útiles
• Licencia
• Sugerencias de mejora

---

Arquitectura

Servicios principales

• app (Node.js / Express): API de negocio y páginas simples para cargar y listar roles, usuarios, categorías y productos.
• auth (Node.js / Express + bcrypt): endpoints de registro e inicio de sesión.
• db (PostgreSQL 16): base de datos de la aplicación.
• tenants (PostgreSQL 16): base de datos separada para multi-tenencia (aislar clientes/tiendas).

Herramientas

• Nginx Proxy Manager (NPM): reverse proxy y certificados (Let’s Encrypt) para exponer servicios.
• CloudBeaver (DBeaver): administración de PostgreSQL vía web.

Redes & Volúmenes

• Redes independientes por entorno (suitecoffee_dev_net / suitecoffee_prod_net).
• Volúmenes gestionados por Compose para persistencia: suitecoffee-db, tenants-db, etc.

Diagrama (alto nivel)

@startuml
skinparam componentStyle rectangle
skinparam rectangle {
  BorderColor #555
  RoundCorner 10
}
actor Usuario

package "Entorno DEV/PROD" {
  [app (Express)] as APP
  [auth (Express + bcrypt)] as AUTH
  database "db (PostgreSQL)" as DB
  database "tenants (PostgreSQL)" as TENANTS
  APP -down-> DB : Pool PG
  APP -down-> TENANTS : Pool PG
  AUTH -down-> DB : Pool PG (usuarios)
  Usuario --> APP : UI / API
  Usuario --> AUTH : Login/Registro
}

package "Herramientas" {
  [Nginx Proxy Manager] as NPM
  [CloudBeaver] as DBVR
  NPM ..> APP : proxy
  NPM ..> AUTH : proxy
  DBVR ..> DB : admin
  DBVR ..> TENANTS : admin
}
@enduml

---

Características principales

• API REST para entidades clave (roles, usuarios, categorías y productos).
• Autenticación básica (registro y login) con hash de contraseñas (bcrypt).
• Multi‑tenencia con base tenants separada para aislar clientes/tiendas.
• Docker Compose v2 con entornos de desarrollo y producción.
• Herramientas integradas (NPM + CloudBeaver) en un compose.tools.yaml aparte.
• Scripts de backup/restauración de volúmenes y gestión de entornos.

---

Requisitos

• Docker y Docker Compose v2 (recomendado).
• Python 3.9+ (para scripts suitecoffee.py, backups y utilidades).
• Node.js 20+ (sólo si vas a ejecutar servicios Node fuera de Docker).

---

Inicio rápido

Opción A — Gestor interactivo (recomendado)

1. Clona el repo y entra al directorio:

   git clone https://gitea.mateosaldain.uy/msaldain/SuiteCoffee.git
   cd SuiteCoffee
   

2. (Opcional) Crea/copía tus archivos .env para app y auth en ./services/<service>/.env.development (ver sección de variables).
3. Ejecuta el gestor:

   python3 suitecoffee.py
   

   • Verás un menú para levantar DESARROLLO o PRODUCCIÓN.
   • Desde ahí también puedes levantar/apagar las herramientas NPM y CloudBeaver.
4. Accede:
   • App (dev): suele estar disponible via NPM o directamente dentro de la red, según tu configuración.
   • Páginas simples: /roles, /usuarios, /categorias, /productos (servidas por app).
   • Salud: /health en app y auth.

Consejo: primero levanta desarrollo/producción y luego las herramientas para que existan las redes externas suitecoffee_dev_net/suitecoffee_prod_net que usa compose.tools.yaml.

Opción B — Comandos Docker Compose (avanzado)

• Desarrollo:

  docker compose -f compose.yaml -f compose.dev.yaml     --env-file ./services/app/.env.development     --env-file ./services/auth/.env.development     -p suitecoffee_dev up -d
  

• Producción:

  docker compose -f compose.yaml -f compose.prod.yaml     --env-file ./services/app/.env.production     --env-file ./services/auth/.env.production     -p suitecoffee_prod up -d
  

Los puertos se exponen para herramientas (NPM UI :81, CloudBeaver :8978); los servicios app y auth se exponen dentro de la red y se publican externamente a través de NPM.

---

Variables de entorno

Crea un archivo .env.development (y uno .env.production) en cada servicio (./services/app y ./services/auth). Variables comunes:

# Servidor
PORT=4000                 # puerto HTTP del servicio
NODE_ENV=development      # development | production

# Base de datos
DB_HOST=db                # nombre del servicio postgres (o host)
DB_LOCAL_PORT=5432        # puerto de PG al que conectarse
DB_USER=postgres
DB_PASS=postgres
DB_NAME=suitecoffee_db    # para 'db' (aplicación)
TENANTS_DB_NAME=tenants_db  # si el servicio necesita apuntar a 'tenants'

Ajusta DB_HOST a db o tenants según corresponda. En desarrollo, los alias útiles son dev-db y dev-tenants; en producción: prod-db y prod-tenants.

---

Endpoints

Servicio app (negocio)

• GET /health
• GET /api/roles — lista roles
• POST /api/roles — crea un rol
• GET /api/usuarios — lista usuarios
• POST /api/usuarios — crea un usuario
• GET /api/categorias — lista categorías
• POST /api/categorias — crea una categoría
• GET /api/productos — lista productos
• POST /api/productos — crea un producto
• Páginas estáticas simples para probar: /roles, /usuarios, /categorias, /productos

Servicio auth (autenticación)

• GET /health
• POST /register — registro de usuario (password con bcrypt)
• POST /auth/login — inicio de sesión

Nota: En esta etapa los endpoints son básicos y pensados para desarrollo/PoC. Ver la sección Sugerencias de mejora para próximos pasos (JWT, autorización, etc.).

---

Estructura del proyecto

SuiteCoffee/
├─ services/
│  ├─ app/
│  │  ├─ src/
│  │  │  ├─ index.js         # API y páginas simples
│  │  │  └─ pages/           # roles.html, usuarios.html, categorias.html, productos.html
│  │  ├─ .env.development    # variables (ejemplo)
│  │  └─ .env.production
│  └─ auth/
│     ├─ src/
│     │  └─ index.js         # /register y /auth/login
│     ├─ .env.development
│     └─ .env.production
├─ compose.yaml              # base (db, tenants)
├─ compose.dev.yaml          # entorno desarrollo (app, auth, db, tenants)
├─ compose.prod.yaml         # entorno producción (app, auth, db, tenants)
├─ compose.tools.yaml        # herramientas (NPM, CloudBeaver) con redes externas
├─ suitecoffee.py            # gestor interactivo (Docker Compose)
├─ backup_compose_volumes.py # backups de volúmenes Compose
└─ restore_compose_volumes.py# restauración de volúmenes Compose

---

Herramientas auxiliares (NPM y CloudBeaver)

Los servicios de herramientas están separados para poder usarlos con ambos entornos (dev y prod) a la vez. Se levantan con compose.tools.yaml y se conectan a las redes externas suitecoffee_dev_net y suitecoffee_prod_net.

• Nginx Proxy Manager (NPM)
  Puertos: 80 (HTTP), 81 (UI). Volúmenes: npm_data, npm_letsencrypt.
• CloudBeaver
  Puerto: 8978. Volúmenes: dbeaver_logs, dbeaver_workspace.

Si es la primera vez, arranca un entorno (dev/prod) para que Compose cree las redes; luego levanta las herramientas:

docker compose -f compose.tools.yaml --profile npm -p suitecoffee up -d
docker compose -f compose.tools.yaml --profile dbeaver -p suitecoffee up -d

---

Backups y restauración de volúmenes

Este repo incluye dos utilidades:

• backup_compose_volumes.py — detecta volúmenes de un proyecto de Compose (por labels y nombres) y los exporta a tar.gz usando un contenedor alpine temporal.
• restore_compose_volumes.py — permite restaurar esos tar.gz en volúmenes (útil para migraciones y pruebas).

Ejemplos básicos

# Listar ayuda
python3 backup_compose_volumes.py --help

# Respaldar volúmenes asociados a "suitecoffee_dev" en ./backups
python3 backup_compose_volumes.py --project suitecoffee_dev --output ./backups

# Restaurar un archivo a un volumen
python3 restore_compose_volumes.py --archive ./backups/suitecoffee_dev_suitecoffee-db-YYYYmmddHHMMSS.tar.gz --volume suitecoffee_dev_suitecoffee-db

Consejo: si migraste manualmente y ves advertencias tipo “volume ... already exists but was not created by Docker Compose”, considera marcar el volumen como external: true en el YAML o recrearlo para que Compose lo etiquete correctamente.

---

Comandos útiles

# Ver estado (menú interactivo)
python3 suitecoffee.py

# Levantar DEV/PROD por menú (con o sin --force-recreate)
python3 suitecoffee.py

# Levantar herramientas (también desde menú)
docker compose -f compose.tools.yaml --profile npm -p suitecoffee up -d
docker compose -f compose.tools.yaml --profile dbeaver -p suitecoffee up -d

# Inspeccionar servicios/volúmenes que Compose detecta desde los YAML
docker compose -f compose.yaml -f compose.dev.yaml config --services
docker compose -f compose.yaml -f compose.dev.yaml config --format json | jq .volumes

---

Licencia

• ISC (ver package.json).

---

Sugerencias de mejora

• Autenticación y seguridad
  • Emitir JWT en el login y proteger rutas (roles/autorización por perfil).
  • Configurar CORS por orígenes (en dev está abierto; en prod restringir).
  • Añadir rate‑limit y helmet en Express.
• Esquema de datos y migraciones
  • Añadir migraciones automatizadas (p.ej. Prisma, Knex, Sequelize o SQL versionado) y seeds iniciales.
  • Clarificar el modelo multi‑tenant: por BD por tenant o schema por tenant; documentar estrategia.
• Calidad & DX
  • Tests (unitarios e integración) y CI básico.
  • Validación de entrada (zod / joi), manejo de errores consistente y logs estructurados.
• Docker/DevOps
  • Documentar variables .env completas por servicio.
  • Publicar imágenes de producción y usar IMAGE:TAG en compose.prod.yaml (evitar build en servidor).
  • Añadir healthchecks a app/auth (ya hay ejemplos comentados).
• Frontend
  • Reemplazar páginas HTML de prueba por un frontend (React/Vite) o una UI admin mínima.
• Pequeños fixes
  • En los HTML de ejemplo corregir las referencias a campos id_rol, id_categoria, etc.
  • Centralizar constantes (nombres de tablas/campos) y normalizar respuestas API.

---