Docs
Instalacion

Instalacion

Como instalar tu aplication.

Guía de Instalación Completa

Requisitos del Sistema

Software Requerido

  • Node.js 18.0.0 o superior
  • Bun runtime 1.0.0+
  • Redis 6.0+ (para desarrollo local)
  • VS Code (recomendado)

Hardware Recomendado

  • CPU: 4 cores o superior
  • RAM: 4GB mínimo (8GB recomendado)
  • Almacenamiento: 2GB libre mínimo
  • Conexión Internet: 10Mbps+

Cuentas Necesarias

  • Vercel (para hosting)
  • OpenAI (API key)
  • Upstash (opcional, para Redis)
  • Serper (opcional, para búsqueda de videos)

1. Preparación del Entorno

Windows

  1. Instala Node.js:
# Usando winget
winget install OpenJS.NodeJS.LTS
# O descarga el instalador de nodejs.org
 
# Verifica instalación 
node --version  # debe mostrar 18.x+
npm --version   # debe mostrar 8.x+
  1. Instala Bun:
# Usando PowerShell (Admin)
curl -fsSL https://bun.sh/install.ps1 | iex
 
# Verifica Bun
bun --version

macOS

# Instala Homebrew si no lo tienes
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 
# Instala dependencias
brew install node
brew install bun
 
# Verifica instalaciones
node --version
bun --version

Linux (Ubuntu/Debian)

# Actualiza sistema
sudo apt update && sudo apt upgrade
 
# Instala Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs
 
# Instala Bun
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc

2. Configuración del Proyecto

  1. Prepara el directorio:
cd aichatbottemplate
  1. Instala todas las dependencias:
bun install
 
# Verifica la instalación correcta
bun run verify
  1. Configura Variables de Entorno:
# Copia el template
cp .env.local.example .env.local
 
# Estructura completa del .env.local:
 
# APIs Requeridas
OPENAI_API_KEY=sk-xxx                    # Requerido
 
# Redis (elige una opción)
USE_LOCAL_REDIS=true                     # Para Redis local
LOCAL_REDIS_URL=redis://localhost:6379   # URL Redis local
# O
UPSTASH_REDIS_REST_URL=xxx               # Para Upstash
UPSTASH_REDIS_REST_TOKEN=xxx             # Para Upstash
 
# Configuración de Búsqueda
SEARXNG_API_URL=http://localhost:8080    
SEARCH_API=searxng                       # searxng o exa
SEARXNG_MAX_RESULTS=50
SEARXNG_DEFAULT_DEPTH=basic              # basic o advanced
 
# APIs Opcionales
ANTHROPIC_API_KEY=xxx                    # Para Claude
GOOGLE_AI_KEY=xxx                        # Para Gemini
GROQ_API_KEY=xxx                         # Para Groq
AZURE_API_KEY=xxx                        # Para Azure OpenAI
SERPER_API_KEY=xxx                       # Para búsqueda de videos
 
# Configuración General
NEXT_PUBLIC_BASE_URL=http://localhost:3000
ENABLE_SHARE=false                       # Habilitar compartir

3. Configuración Redis

Opción A: Redis Local

  1. Instala Redis:
# Ubuntu/Debian
sudo apt install redis-server
 
# macOS
brew install redis
 
# Windows: Descarga Redis Stack
  1. Configura Redis:
# Edita redis.conf
sudo nano /etc/redis/redis.conf
 
# Configuración recomendada:
maxmemory 512mb
maxmemory-policy allkeys-lru
appendonly yes
  1. Inicia y verifica:
# Inicia servicio
sudo systemctl start redis-server
 
# Verifica estado
sudo systemctl status redis-server
 
# Prueba conexión
redis-cli ping  # Debe responder "PONG"

Opción B: Upstash Redis

  1. Regístrate en Upstash
  2. Crea nueva base de datos:
    • Selecciona región cercana
    • Escoge plan gratuito para desarrollo
    • Copia credenciales REST
  3. Configura variables en .env.local: 
    UPSTASH_REDIS_REST_URL=xxx
UPSTASH_REDIS_REST_TOKEN=xxx

4. Desarrollo Local

  1. Inicia el servidor de desarrollo:
bun dev

  1. Verifica en http://localhost:3000

  2. Prueba funcionalidades principales:

  • Realiza una búsqueda
  • Verifica respuesta de IA
  • Comprueba almacenamiento en Redis
  • Prueba diferentes modelos de IA

5. Despliegue en Vercel

  1. Prepara el proyecto:
bun run build  # Verifica build local primero
  1. Configura Vercel:
  • Crea cuenta en Vercel
  • Instala Vercel CLI: npm i -g vercel
  • Login: vercel login
  1. Configura proyecto:
vercel
# Responde las preguntas:
# - Set up and deploy? Yes
# - Directory? ./
# - Override settings? No
  1. Configura variables de entorno en Vercel:
  • Ve a Dashboard → Settings → Environment Variables
  • Copia todas las variables de .env.local
  • Asegúrate de agregar NEXT_PUBLIC_BASE_URL
  1. Despliega:
vercel --prod
  1. Verifica deployment:
  • Prueba búsquedas
  • Verifica conexión Redis
  • Comprueba modelos IA
  • Prueba compartir (si está habilitado)

6. Scripts Disponibles

# Desarrollo
bun dev             # Servidor desarrollo
bun dev:turbo       # Desarrollo con Turbo (más rápido)
bun type-check      # Verifica tipos
bun lint           # Ejecuta linter
 
# Producción  
bun build          # Construye app
bun start          # Inicia producción
bun analyze        # Analiza bundle
 
# Testing
bun test           # Ejecuta tests  
bun test:watch     # Tests en watch mode

7. Solución de Problemas

Problemas Comunes Redis

# Error de conexión
sudo systemctl restart redis-server
redis-cli config get databases  # Verifica configuración
 
# Memoria insuficiente 
redis-cli info memory  # Verifica uso
sudo sysctl vm.overcommit_memory=1  # Ajusta si necesario

Errores de API

# Rate Limit
- Implementa exponential backoff
- Aumenta intervalo entre requests
- Verifica límites de plan
 
# Timeout
- Aumenta timeout en fetch
- Implementa retry logic
- Usa streaming cuando posible

Problemas de Build

# Error: Cannot find module
bun install        # Reinstala módulos
rm -rf .next      # Limpia cache
bun clean         # Limpia build
 
# Error: Type checking failed  
bun type-check    # Verifica tipos
bun install --force  # Fuerza reinstalación

8. Verificación Final

Checklist Local

  1. ✓ Servidor inicia sin errores
  2. ✓ Redis conecta y persiste datos
  3. ✓ Búsquedas retornan resultados
  4. ✓ IA genera respuestas
  5. ✓ UI responde correctamente

Checklist Producción

  1. ✓ Build completa sin errores
  2. ✓ Todas las variables están configuradas
  3. ✓ Redis conecta en producción
  4. ✓ APIs responden correctamente
  5. ✓ Performance es óptima

Monitoreo

  1. Verifica logs en Vercel
  2. Monitorea uso de Redis
  3. Revisa límites de API
  4. Comprueba métricas de performance

9. Optimización

Performance

  1. Implementa caché agresivo
  2. Usa streaming para respuestas largas
  3. Optimiza imágenes y assets
  4. Minimiza JavaScript

Costos

  1. Monitorea uso de APIs
  2. Implementa rate limiting
  3. Optimiza consultas Redis
  4. Usa tier gratuito cuando posible
Plataforma EcommercePlataforma SaaS