Manual de Usuario - Guía de Instalación

Configuración Base del Sistema

1. Requisitos Iniciales

const systemRequirements = {
  // Software necesario
  software: {
    node: '18.0.0+',
    bun: '1.0.0+',
    redis: '6.0+',
    editor: 'VS Code'
  },
 
  // Hardware mínimo
  hardware: {
    cpu: '4 cores',
    ram: {
      minimum: '4GB',
      recommended: '8GB'
    },
    storage: '2GB',
    internet: '10Mbps+'
  },
 
  // Cuentas requeridas
  accounts: {
    required: ['Vercel', 'OpenAI'],
    optional: ['Upstash', 'Serper']
  }
}

2. Instalación por Sistema Operativo

export const installationSteps = {
  windows: {
    node: {
      command: 'winget install OpenJS.NodeJS.LTS',
      verify: 'node --version && npm --version'
    },
    bun: {
      command: 'curl -fsSL https://bun.sh/install.ps1 | iex',
      verify: 'bun --version'
    }
  },
  
  macos: {
    base: 'brew install node bun',
    verify: [
      'node --version',
      'bun --version'
    ]
  },
 
  linux: {
    prepare: 'sudo apt update && sudo apt upgrade',
    node: {
      setup: 'curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -',
      install: 'sudo apt install -y nodejs'
    },
    bun: {
      install: 'curl -fsSL https://bun.sh/install | bash',
      config: 'source ~/.bashrc'
    }
  }
}

3. Configuración del Proyecto

export const projectSetup = {
  // Inicialización
  init: {
    directory: 'cd searchtemplate',
    install: 'bun install',
    verify: 'bun run verify'
  },
 
  // Variables de entorno
  envConfig: {
    required: {
      OPENAI_API_KEY: 'sk-xxx'
    },
    redis: {
      local: {
        USE_LOCAL_REDIS: true,
        LOCAL_REDIS_URL: 'redis://localhost:6379'
      },
      upstash: {
        UPSTASH_REDIS_REST_URL: 'xxx',
        UPSTASH_REDIS_REST_TOKEN: 'xxx'
      }
    },
    search: {
      SEARXNG_API_URL: 'http://localhost:8080',
      SEARCH_API: 'searxng',
      options: {
        MAX_RESULTS: 50,
        DEFAULT_DEPTH: 'basic'
      }
    },
    optional: {
      ANTHROPIC_API_KEY: 'xxx',
      GOOGLE_AI_KEY: 'xxx',
      GROQ_API_KEY: 'xxx',
      AZURE_API_KEY: 'xxx',
      SERPER_API_KEY: 'xxx'
    }
  }
}

Configuración de Redis

1. Instalación Local

const redisLocal = {
  // Instalación por sistema
  install: {
    ubuntu: 'sudo apt install redis-server',
    macos: 'brew install redis',
    windows: 'Redis Stack Download'
  },
 
  // Configuración base
  config: {
    path: '/etc/redis/redis.conf',
    settings: {
      maxmemory: '512mb',
      policy: 'allkeys-lru',
      persistence: 'appendonly yes'
    }
  },
 
  // Gestión del servicio
  service: {
    start: 'sudo systemctl start redis-server',
    verify: [
      'sudo systemctl status redis-server',
      'redis-cli ping'
    ]
  }
}

2. Configuración Upstash

const upstashSetup = {
  steps: [
    'Registro en upstash.com',
    'Crear nueva base de datos',
    'Configurar región cercana',
    'Seleccionar plan gratuito',
    'Copiar credenciales REST'
  ],
  
  envVars: {
    UPSTASH_REDIS_REST_URL: 'xxx',
    UPSTASH_REDIS_REST_TOKEN: 'xxx'
  }
}

Desarrollo y Despliegue

1. Ambiente de Desarrollo

const devEnvironment = {
  // Comandos principales
  commands: {
    dev: 'bun dev',
    url: 'http://localhost:3000',
    tests: [
      'Búsqueda base',
      'Respuesta IA',
      'Redis storage',
      'Modelos IA'
    ]
  }
}

2. Despliegue Vercel

const vercelDeploy = {
  // Preparación
  prepare: {
    build: 'bun run build',
    cli: 'npm i -g vercel',
    auth: 'vercel login'
  },
 
  // Configuración
  setup: {
    command: 'vercel',
    options: {
      deploy: true,
      directory: './',
      override: false
    }
  },
 
  // Variables de entorno
  env: {
    path: 'Dashboard → Settings → Environment Variables',
    required: [
      'Copiar .env.local',
      'Añadir NEXT_PUBLIC_BASE_URL'
    ]
  },
 
  // Despliegue final
  deploy: {
    command: 'vercel --prod',
    verify: [
      'Búsquedas',
      'Conexión Redis',
      'Modelos IA',
      'Sharing'
    ]
  }
}

Comandos Disponibles

1. Desarrollo

export const devCommands = {
  standard: 'bun dev',
  turbo: 'bun dev:turbo',
  typeCheck: 'bun type-check',
  lint: 'bun lint'
}

2. Producción

export const prodCommands = {
  build: 'bun build',
  start: 'bun start',
  analyze: 'bun analyze'
}

3. Testing

export const testCommands = {
  run: 'bun test',
  watch: 'bun test:watch'
}

Resolución de Problemas

1. Redis

const redisTroubleshooting = {
  connection: {
    restart: 'sudo systemctl restart redis-server',
    verify: 'redis-cli config get databases'
  },
  memory: {
    check: 'redis-cli info memory',
    fix: 'sudo sysctl vm.overcommit_memory=1'
  }
}

2. API

const apiTroubleshooting = {
  rateLimit: [
    'Implementar exponential backoff',
    'Aumentar intervalo entre requests',
    'Verificar límites de plan'
  ],
  timeout: [
    'Aumentar timeout en fetch',
    'Implementar retry logic',
    'Usar streaming cuando posible'
  ]
}

3. Build

const buildTroubleshooting = {
  moduleError: {
    steps: [
      'bun install',
      'rm -rf .next',
      'bun clean'
    ]
  },
  typeError: {
    steps: [
      'bun type-check',
      'bun install --force'
    ]
  }
}

Verificación y Optimización

1. Checklists

const verificationLists = {
  local: [
    'Servidor sin errores',
    'Redis conectado',
    'Búsquedas funcionando',
    'IA respondiendo',
    'UI responsiva'
  ],
  production: [
    'Build exitoso',
    'Variables configuradas',
    'Redis conectado',
    'APIs respondiendo',
    'Performance óptima'
  ]
}

2. Monitoreo y Optimización

const monitoring = {
  checks: [
    'Logs en Vercel',
    'Uso de Redis',
    'Límites API',
    'Métricas performance'
  ],
  
  optimization: {
    performance: [
      'Caché agresivo',
      'Streaming responses',
      'Optimizar assets',
      'Minimizar JS'
    ],
    costs: [
      'Monitorear APIs',
      'Rate limiting',
      'Optimizar Redis',
      'Usar tier gratuito'
    ]
  }
}

Plataforma Ecommerce Plataforma SaaS