app-padel/docs/SETUP.md

🚀 Guía de Instalación - App Canchas de Pádel

Guía completa para configurar el entorno de desarrollo y producción.

📋 Requisitos

Requisitos del Sistema

Componente	Versión Mínima	Recomendado
Node.js	18.x	20.x LTS
npm	9.x	10.x
PostgreSQL	14.x	16.x
Git	2.x	Latest

Especificaciones de Hardware

Entorno	CPU	RAM	Disco
Desarrollo	2 cores	4 GB	20 GB SSD
Producción	4+ cores	8+ GB	50+ GB SSD

---

🛠️ Instalación Paso a Paso

1. Clonar el Repositorio

git clone https://github.com/tu-usuario/app-padel.git
cd app-padel

2. Instalar Dependencias del Backend

cd backend
npm install

3. Configurar Variables de Entorno

Copiar el archivo de ejemplo:

cp .env.example .env

Editar el archivo .env con tus valores:

# ============================================
# Configuración de la Base de Datos
# ============================================
DATABASE_URL="postgresql://postgres:tu_password@localhost:5432/app_padel?schema=public"

# ============================================
# Configuración del Servidor
# ============================================
NODE_ENV=development
PORT=3000
API_URL=http://localhost:3000
FRONTEND_URL=http://localhost:5173

# ============================================
# Configuración de JWT
# ============================================
JWT_SECRET=tu_clave_secreta_super_segura_aleatoria_32chars
JWT_EXPIRES_IN=7d
JWT_REFRESH_SECRET=otra_clave_secreta_diferente_32chars
JWT_REFRESH_EXPIRES_IN=30d

# ============================================
# Configuración de Email (SMTP)
# ============================================
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=tu_email@gmail.com
SMTP_PASS=tu_app_password_de_gmail
EMAIL_FROM="Canchas Padel <noreply@tudominio.com>"

# ============================================
# Configuración de Rate Limiting
# ============================================
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

# ============================================
# Configuración de MercadoPago (Producción)
# ============================================
MERCADOPAGO_ACCESS_TOKEN=APP_USR-0000000000000000-000000-00000000000000000000000000000000-000000000
MERCADOPAGO_PUBLIC_KEY=APP_USR-00000000-0000-0000-0000-000000000000

4. Crear Base de Datos

# Conectar a PostgreSQL
sudo -u postgres psql

# Crear base de datos
CREATE DATABASE app_padel;

# Crear usuario (opcional)
CREATE USER app_padel_user WITH PASSWORD 'tu_password_seguro';
GRANT ALL PRIVILEGES ON DATABASE app_padel TO app_padel_user;

# Salir
\q

5. Ejecutar Migraciones

# Generar cliente Prisma
npm run db:generate

# Ejecutar migraciones
npm run db:migrate

6. Seed de Datos (Opcional)

# Ejecutar seed para datos de prueba
npm run db:seed

Este comando creará:

• Usuario admin por defecto
• Canchas de ejemplo
• Planes de suscripción
• Logros del sistema

7. Iniciar Servidor en Desarrollo

npm run dev

El servidor estará disponible en: http://localhost:3000

---

🔧 Configuración Avanzada

Variables de Entorno Completas

Base de Datos

Variable	Descripción	Ejemplo
DATABASE_URL	URL de conexión PostgreSQL	postgresql://user:pass@host:5432/db

Servidor

Variable	Descripción	Default
NODE_ENV	Entorno (development/production)	development
PORT	Puerto del servidor	3000
API_URL	URL base de la API	http://localhost:3000
FRONTEND_URL	URL del frontend (CORS)	http://localhost:5173

Seguridad (JWT)

Variable	Descripción	Recomendación
JWT_SECRET	Secreto para tokens	Mínimo 32 caracteres aleatorios
JWT_EXPIRES_IN	Duración del access token	7d
JWT_REFRESH_SECRET	Secreto para refresh tokens	Diferente al JWT_SECRET
JWT_REFRESH_EXPIRES_IN	Duración del refresh token	30d

Email (SMTP)

Variable	Descripción	Ejemplo
SMTP_HOST	Servidor SMTP	smtp.gmail.com
SMTP_PORT	Puerto SMTP	587
SMTP_USER	Usuario SMTP	tucorreo@gmail.com
SMTP_PASS	Contraseña SMTP	app_password
EMAIL_FROM	Remitente por defecto	Canchas <noreply@tudominio.com>

Rate Limiting

Variable	Descripción	Default
RATE_LIMIT_WINDOW_MS	Ventana en ms	900000 (15 min)
RATE_LIMIT_MAX_REQUESTS	Máximo requests	100

MercadoPago

Variable	Descripción	Ejemplo
MERCADOPAGO_ACCESS_TOKEN	Token de acceso MP	APP_USR-...
MERCADOPAGO_PUBLIC_KEY	Clave pública MP	APP_USR-...
MERCADOPAGO_WEBHOOK_SECRET	Secreto para webhooks	webhook_secret

---

🧪 Ejecución en Desarrollo

Scripts Disponibles

# Desarrollo con hot reload
npm run dev

# Build para producción
npm run build

# Producción (requiere build previo)
npm start

# Base de datos
npm run db:generate    # Generar cliente Prisma
npm run db:migrate     # Ejecutar migraciones
npm run db:studio      # Abrir Prisma Studio
npm run db:seed        # Ejecutar seed

# Calidad de código
npm run lint           # Ejecutar ESLint
npm test              # Ejecutar tests

Estructura de Archivos en Desarrollo

backend/
├── src/
│   ├── config/        # Configuraciones
│   ├── controllers/   # Controladores
│   ├── middleware/    # Middlewares
│   ├── routes/        # Rutas
│   ├── services/      # Lógica de negocio
│   ├── utils/         # Utilidades
│   ├── validators/    # Validaciones Zod
│   └── index.ts       # Entry point
├── prisma/
│   └── schema.prisma  # Esquema de base de datos
├── logs/              # Archivos de log
├── .env               # Variables de entorno
└── package.json

---

🚀 Ejecución en Producción

1. Preparar el Build

# Instalar dependencias de producción
npm ci --only=production

# Compilar TypeScript
npm run build

2. Configurar PM2

Crear archivo ecosystem.config.js:

module.exports = {
  apps: [{
    name: 'app-padel-api',
    script: './dist/index.js',
    instances: 'max',
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'production',
      PORT: 3000
    },
    log_file: './logs/combined.log',
    out_file: './logs/out.log',
    error_file: './logs/error.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
    merge_logs: true,
    max_memory_restart: '1G',
    restart_delay: 3000,
    max_restarts: 5,
    min_uptime: '10s'
  }]
};

3. Iniciar con PM2

# Iniciar aplicación
pm2 start ecosystem.config.js

# Guardar configuración
pm2 save

# Configurar inicio automático
pm2 startup

4. Verificar Estado

pm2 status
pm2 logs app-padel-api

---

🐳 Docker (Alternativa)

Usar Docker Compose

# Iniciar todos los servicios
docker-compose up -d

# Ver logs
docker-compose logs -f backend

# Ejecutar migraciones
docker-compose exec backend npx prisma migrate deploy

Dockerfile (Backend)

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 3000

CMD ["node", "dist/index.js"]

---

✅ Verificación de Instalación

Health Check

# Verificar API
curl http://localhost:3000/api/v1/health

# Respuesta esperada
{
  "success": true,
  "message": "API funcionando correctamente",
  "timestamp": "2026-01-31T12:00:00.000Z"
}

Lista de Endpoints

# Ver todas las rutas disponibles
curl http://localhost:3000/api/v1

---

🔍 Troubleshooting

Error: "Cannot find module"

# Reinstalar dependencias
rm -rf node_modules package-lock.json
npm install

Error de conexión a base de datos

# Verificar PostgreSQL
sudo systemctl status postgresql

# Verificar conexión
psql $DATABASE_URL -c "SELECT 1"

Error: "Prisma schema not found"

# Regenerar cliente
npx prisma generate

Puerto 3000 en uso

# Encontrar proceso
lsof -i :3000

# O cambiar el puerto en .env
PORT=3001

---

📚 Recursos Adicionales

• Documentación API
• Guía de Deploy
• Prisma Documentation
• Express.js Guide

---

Última actualización: Enero 2026