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 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

Servicios principales

Herramientas

Redes & Volúmenes

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

Requisitos

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
  4. Accede:

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)

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)

Servicio auth (autenticació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.

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:

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

Sugerencias de mejora