Guía de Instalación

Esta guía te ayudará a instalar y configurar UnoSportClub en Firebase desde cero.

Requisitos Previos

Antes de comenzar, asegúrate de tener instalado:

  • Node.js 22 o superior

  • npm 9 o superior

  • Git

  • Una cuenta de Firebase

  • Una base de datos PostgreSQL (local o en la nube)

Verificar Instalaciones

node --version    # Debe ser v22.x o superior
npm --version     # Debe ser 9.x o superior
git --version

Instalación de Firebase CLI

Instala Firebase CLI globalmente:

npm install -g firebase-tools

Verifica la instalación:

firebase --version

Inicia sesión en Firebase:

firebase login

Configuración del Proyecto Firebase

Crear Proyecto en Firebase Console

  1. Ve a https://console.firebase.google.com/

  2. Haz clic en "Agregar proyecto"

  3. Ingresa el nombre del proyecto (ej: unosportclub-dev)

  4. Sigue las instrucciones para completar la creación

Inicializar Firebase en el Proyecto Local

Clona o navega al directorio del proyecto:

cd unosportclub
firebase init

Durante la inicialización, selecciona:

  • Firebase Features: Hosting, Functions

  • Project: Selecciona el proyecto creado anteriormente

  • Functions:

    • Language: JavaScript

    • ESLint: Yes

    • Install dependencies: Yes

  • Hosting:

    • Public directory: dist/unosportclub/browser

    • Single-page app: Yes

    • Set up automatic builds: No (por ahora)

Configuración de Variables de Entorno

Variables de Entorno para Functions

Crea el archivo functions/.env:

cd functions
cp .env.example .env

Edita functions/.env y configura:

# Configuración de Base de Datos PostgreSQL
DATABASE_URL=postgresql://usuario:password@host:puerto/nombre_bd

# O usa variables individuales:
# DB_HOST=localhost
# DB_PORT=5432
# DB_NAME=unosportclub
# DB_USER=postgres
# DB_PASSWORD=tu_password
# DB_SSL=false

Variables de Entorno para Firebase Functions (Producción)

Para producción, configura las variables usando Firebase Functions Config o Secret Manager:

Opción 1: Firebase Functions Config (valores no sensibles)

firebase functions:config:set db.host="tu-host" db.port="5432" db.name="unosportclub"

Opción 2: Secret Manager (valores sensibles - RECOMENDADO)

# Crear secreto
firebase functions:secrets:set DATABASE_URL

# Se te pedirá ingresar el valor del secreto
# Ingresa: postgresql://usuario:password@host:puerto/nombre_bd

Luego, en functions/index.js, accede al secreto:

const { defineSecret } = require('firebase-functions/params');
const databaseUrl = defineSecret('DATABASE_URL');

Instalación de Dependencias

Dependencias del Proyecto Principal

npm install

Este comando también ejecutará automáticamente las migraciones de base de datos si las variables de entorno están configuradas.

Dependencias de Functions

cd functions
npm install

Configuración de Base de Datos PostgreSQL

Crear Base de Datos

Si usas PostgreSQL local:

createdb unosportclub

Si usas un servicio en la nube (Render, Heroku, AWS RDS, etc.), sigue las instrucciones de tu proveedor para crear la base de datos.

Ejecutar Migraciones y Seeders

Las migraciones se ejecutan automáticamente durante npm install si las variables de entorno están configuradas.

Para ejecutarlas manualmente:

npm run db:migrate

Este comando: * Crea todas las tablas del modelo de datos * Carga los datos iniciales (tipos de cancha, tipos de cliente, tipos de reserva)

Verificar Instalación de Base de Datos

Puedes verificar que todo se haya instalado correctamente conectándote a PostgreSQL:

psql -h localhost -U postgres -d unosportclub -c "\dt"

Deberías ver las siguientes tablas:

  • user

  • client_type

  • court_type

  • reservation_type

  • operator

  • client

  • court

  • reservation

  • payment

  • discount

  • schema_migrations

Configuración de Firebase Functions

Estructura de Functions

El proyecto usa Express.js dentro de Firebase Functions. La estructura es:

functions/
├── index.js              # Punto de entrada principal
├── routes/               # Rutas de la API
│   ├── bookings.js
│   ├── clients.js
│   ├── courts.js
│   ├── payments.js
│   └── sudo.js
├── models/               # Modelos de datos
├── db/                   # Migraciones y seeders
│   ├── migrations/
│   └── seeders/
└── package.json

Configurar Conexión a Base de Datos en Functions

Asegúrate de que functions/index.js cargue las variables de entorno:

require('dotenv').config();

Y que use el pool de conexiones correctamente:

const { pool } = require('./db');

Configuración de Firebase Hosting

Build de la Aplicación Angular

Antes de desplegar, construye la aplicación:

npm run build

Esto generará los archivos estáticos en dist/unosportclub/browser/.

Configuración de Hosting Múltiple

El proyecto tiene dos sitios de hosting configurados:

  • prod: Aplicación principal (dist/unosportclub/browser)

  • control: Panel de control (dist/sudo/browser)

Para configurar los targets:

firebase target:apply hosting prod unosportclub-prod
firebase target:apply hosting control unosportclub-control

Despliegue

Desplegar Functions

firebase deploy --only functions

O desplegar una función específica:

firebase deploy --only functions:api
firebase deploy --only functions:sudo

Desplegar Hosting

firebase deploy --only hosting

O desplegar un target específico:

firebase deploy --only hosting:prod
firebase deploy --only hosting:control

Desplegar Todo

firebase deploy

Verificación Post-Instalación

Verificar Functions

Después del despliegue, verifica que las funciones estén activas:

firebase functions:list

Verificar Hosting

Visita las URLs de tus sitios:

Verificar API

Prueba los endpoints de la API:

curl https://tu-proyecto.web.app/api/api-docs.json

Solución de Problemas

Error: Variables de Entorno No Configuradas

Si ves el mensaje:

⚠️  Variables de entorno de base de datos no configuradas

Verifica que: * El archivo functions/.env existe * Las variables están correctamente configuradas * El archivo no tiene errores de sintaxis * No hay espacios extra alrededor del signo = * Las comillas están correctamente cerradas

Error: Conexión a Base de Datos Fallida

Verifica: * Que PostgreSQL esté corriendo * Que las credenciales sean correctas * Que el firewall permita conexiones desde Firebase Functions * Que uses SSL si es requerido (bases de datos en la nube) * Que el puerto esté abierto (por defecto 5432) * Que la base de datos exista

Para probar la conexión manualmente:

npm run db:test

Error: Migraciones No Se Ejecutan

Si las migraciones no se ejecutan automáticamente:

npm run db:migrate

Si hay errores en las migraciones:

  • Revisa los logs de error

  • Verifica que no haya migraciones duplicadas

  • Confirma que la base de datos esté vacía o en el estado correcto

  • Revisa que todas las dependencias de las migraciones estén creadas

Error: Build de Angular Falla

Asegúrate de: * Tener todas las dependencias instaladas: npm install * Tener Node.js 22 o superior * Verificar errores de TypeScript: npm run build * Limpiar caché: rm -rf node_modules .angular && npm install * Verificar que no haya conflictos de versiones

Error: Firebase Functions No Se Despliegan

Si las Functions no se despliegan:

  • Verifica que estés autenticado: firebase login

  • Confirma que el proyecto esté seleccionado: firebase use <project-id>

  • Revisa los logs: firebase functions:log

  • Verifica que no haya errores de sintaxis en functions/index.js

  • Asegúrate de que todas las dependencias estén instaladas en functions/

Error: Hosting No Se Despliega

Si el hosting no se despliega:

  • Verifica que los builds se completen correctamente

  • Confirma que los directorios de salida sean correctos en firebase.json

  • Revisa que los targets estén configurados: firebase target:apply hosting <target> <site>

  • Verifica permisos de Firebase Hosting en la consola

Error: Autenticación No Funciona

Si la autenticación no funciona:

  • Verifica que Firebase Authentication esté habilitado en la consola

  • Confirma que los métodos de autenticación estén activados

  • Revisa la configuración de Firebase en los archivos de entorno

  • Verifica que los dominios autorizados estén configurados

  • Revisa la consola del navegador para errores de JavaScript

Error: API Retorna 404

Si los endpoints de la API retornan 404:

  • Verifica que las Functions estén desplegadas

  • Confirma que las rutas estén correctamente configuradas en functions/index.js

  • Revisa las reglas de rewrite en firebase.json

  • Verifica que el endpoint esté correctamente montado

  • Revisa los logs de Functions para más detalles

Error: Base de Datos en la Nube No Conecta

Para bases de datos en la nube (Render, Heroku, AWS RDS, etc.):

  • Verifica que la IP de Firebase Functions esté en la whitelist

  • Confirma que SSL esté habilitado y configurado

  • Revisa que la URL de conexión incluya parámetros SSL si es necesario

  • Verifica que el usuario de la base de datos tenga los permisos correctos

  • Confirma que la base de datos acepte conexiones externas

Comandos Útiles

Desarrollo Local

# Iniciar emuladores de Firebase
firebase emulators:start

# Ejecutar migraciones manualmente
npm run db:migrate

# Ejecutar seeders manualmente
npm run db:seed

# Desinstalar base de datos (CUIDADO: elimina todo)
npm run db:uninstall

Producción

# Ver logs de Functions
firebase functions:log

# Ver logs en tiempo real
firebase functions:log --follow

# Ver estado del proyecto
firebase projects:list

Verificación Post-Instalación

Checklist de Verificación

Después de la instalación, verifica que todo funcione correctamente:

[ ] Base de Datos: [ ] Las migraciones se ejecutaron sin errores [ ] Las tablas están creadas correctamente [ ] Los seeders cargaron datos iniciales [ ] La conexión funciona desde Functions

[ ] Firebase Functions: [ ] Las Functions están desplegadas [ ] Los endpoints responden correctamente [ ] La autenticación funciona [ ] Los logs no muestran errores críticos

[ ] Firebase Hosting: [ ] Los sitios están desplegados [ ] Las aplicaciones cargan correctamente [ ] Las rutas funcionan (SPA) [ ] Los assets se cargan correctamente

[ ] Autenticación: [ ] Los usuarios pueden registrarse [ ] Los usuarios pueden iniciar sesión [ ] Los roles se asignan correctamente [ ] Los custom claims funcionan

[ ] Aplicaciones: [ ] La aplicación principal carga [ ] El panel de operador funciona [ ] El panel de entrenador funciona [ ] El panel de control funciona

Pruebas Básicas

Realiza estas pruebas básicas:

  1. Crear un usuario de prueba:

    • Regístrate en la aplicación principal

    • Verifica que recibas el email de confirmación

    • Inicia sesión con las credenciales

  2. Probar la API:

    • Haz una petición a /api/api-docs.json

    • Verifica que retorne la documentación Swagger

    • Prueba un endpoint autenticado

  3. Verificar base de datos:

    • Conecta a PostgreSQL

    • Verifica que las tablas existan

    • Confirma que haya datos en las tablas de seeders

Próximos Pasos

Una vez completada la instalación y verificación:

  1. Configuración inicial:

    • Crea el primer usuario super usuario

    • Configura la información básica del club

    • Define las primeras canchas y tarifas

  2. Personalización:

    • Configura Firebase Authentication según tus necesidades

    • Personaliza los dominios en Firebase Hosting

    • Ajusta las configuraciones del sistema

  3. Documentación:

  4. Producción:

    • Configura monitoreo y alertas

    • Establece políticas de backup

    • Configura dominios personalizados

    • Revisa la seguridad y permisos

Recursos Adicionales