Zertipower / Ris3CAT
Plataforma de gestión de comunidades energéticas ciudadanas: reparto de la energía generada entre los miembros, seguimiento del consumo y la producción, gobernanza de la comunidad y simulación de ahorro.
Este repositorio contiene el sistema entero —dos APIs, tres aplicaciones web, la base de datos y esta documentación— y se levanta con un solo comando.
Requisitos mínimos
| Software | Docker. Y nada más: ni Node, ni npm, ni MariaDB. Si falta, el instalador lo pone solo. |
| Sistema | Windows 10 versión 2004 (build 19041) o superior, macOS, o cualquier Linux con Docker. |
| Disco | Unos 5 GB para las imágenes. Reserva 15 GB para la primera compilación: la caché intermedia ocupa bastante y se puede limpiar después con docker builder prune. |
| Memoria | 8 GB recomendados. La primera vez se compilan tres aplicaciones Angular, que es lo que más consume; después basta con mucho menos. |
| Tiempo | La primera instalación tarda varios minutos. Los arranques siguientes son inmediatos. |
Windows corta las rutas a 260 caracteres y algunos archivos del Contador son
profundos —el más largo mide 155—. Si el proyecto acaba en una carpeta ya de por
sí honda, la descarga se queda a medias con un Filename too long, y el error
que verás luego al instalar no se parecerá en nada a la causa.
La solución vale para los dos métodos: deja el proyecto en una ruta corta,
como C:\ris3cat.
Si vas a clonar con git, además puedes quitar el límite de una vez por todas:
git config --global core.longpaths true
Instalación
1. Descarga el proyecto
Hay dos maneras. La primera no necesita tener nada instalado:
📦 Descargar el proyecto en .zip
Descomprímelo donde quieras —en Windows, mejor en una ruta corta— y entra en la
carpeta que crea. Se llamará ris3cat-mono-master.
O, si tienes git y prefieres poder actualizar con git pull más adelante:
git clone https://github.com/zertifier/ris3cat-mono.git
cd ris3cat-mono
El .zip no exige instalar nada y trae exactamente los mismos archivos, con los
finales de línea correctos en cada sistema. Lo único que pierdes es poder traerte
los cambios después con git pull: para actualizar hay que volver a descargarlo.
Mientras lo sea, los dos métodos piden identificarse: el enlace del .zip sólo
funciona con la sesión de GitHub iniciada y con acceso al repositorio, y git clone pedirá credenciales. Si la descarga devuelve un 404, no es que el enlace
esté roto: es que esa cuenta no tiene acceso.
2. Arranca
En Linux o macOS:
./setup.sh
En Windows, haz doble clic en setup.bat, o desde la terminal:
setup.bat
El instalador comprueba los requisitos y, si falta Docker —o WSL 2 en Windows—, lo instala él mismo. Después crea la base de datos, la rellena y levanta todo.
| Opción | Para qué |
|---|---|
| (ninguna) | Instala lo que falte y arranca. Sólo pregunta antes de reiniciar. |
--desatendido / -Desatendido | No pregunta nada. Si hace falta reiniciar, reinicia. |
--sin-instalar / -SinInstalar | No instala nada: sólo comprueba y arranca. |
Te pedirá las claves del acceso con Google
El instalador configura el sistema él solo y escribe un .env completo. La
única parada es el acceso con Google: te pide el client ID y su client
secret, que son lo único que no puede deducir, y te enseña de dónde sacarlos.
Son unos diez minutos en Google Cloud Console, es gratis y no hace falta tarjeta. Si lo tienes hecho, el Panel queda funcionando del todo en el primer arranque.
Todo lo demás se resuelve solo: las contraseñas y las claves de firma se generan
al azar, y las claves de servicios externos quedan escritas en el .env, cada
una con un comentario que explica para qué sirve. El catálogo completo está en
Gestión de secretos.
.env pero está incompletoEl instalador lo detecta y pregunta sólo las que faltan, añadiéndolas al
archivo. Lo que ya tiene —comentarios incluidos— no se toca, y antes de
modificarlo deja una copia en .env.backup-<fecha>.
Antes esto fallaba más tarde y peor: el instalador se apartaba al ver el archivo,
y el error salía dentro de Compose (required variable ... is missing a value)
con la instalación ya terminada.
En modo --desatendido no pregunta: genera las que sabe generar y avisa de las
que quedan vacías, sin detenerse.
Qué queda levantado
| Módulo | Enlace | Puerto |
|---|---|---|
| Panel de Administración | http://localhost:4201 | 4201 |
| Calculadora de autoconsumo | http://localhost:4202 | 4202 |
| Documentación (esto que estás leyendo) | http://localhost:8080 | 8080 |
| API de Zertipower (Swagger) | http://localhost:3000/api | 3000 |
| API de energía en tiempo real (Swagger) | http://localhost:3002/api-docs | 3002 |
| Base de datos MariaDB | 127.0.0.1:3306 | 3306 |
Usuario por defecto
La base de datos se crea con un único usuario administrador:
| Usuario | Contraseña |
|---|---|
admin | admin123 |
Entra con él en el Panel de Administración. Es un usuario de prueba del seed inicial: cámbiale la contraseña o bórralo antes de exponer nada a Internet.
El acceso con Google necesita credenciales propias de Google Cloud, que no vienen en el repositorio. Para configurarlo, ver Acceso con Google, paso a paso.
El Contador no arranca por defecto
El Contador / Smart Meter y su API quedan fuera del arranque normal porque sólo permiten entrar con Google contra un servicio externo. Para levantarlos:
./dev.sh --profile smart-meter up -d
Quedan en http://localhost:4200, con su API en el 3001. Ver Contador / Smart Meter.
Manejo diario
Usa ./dev.sh (o dev.bat) en lugar de docker compose a secas:
./dev.sh ps
./dev.sh logs -f backend
./dev.sh down
Hace falta porque el compose exige dos valores sin defecto —DB_PASSWORD y
JWT_SECRET—, y sin ellos cualquier comando de compose falla, incluso ps.
dev.sh los rellena con valores de desarrollo y pasa el resto de argumentos tal
cual.
El .env que deja el instalador ya trae esos dos valores, y Compose los lee
solo. dev.sh sirve para trabajar sobre un clon recién hecho, sin haber
ejecutado setup.sh.
Por dónde seguir
- Módulos — qué hace cada pieza y cómo configurarla.
- Variables de entorno — el catálogo completo.
- Gestión de secretos — qué es cada clave.
- Acceso con Google — cómo crear el cliente de OAuth.
- Desplegar en un servidor — con HTTPS.
- Solución de problemas — los fallos que más se repiten.