Horux_back/docs/INSTALLATION.md

# Guia de Instalacion - Horux Backend

Guia completa para instalar y configurar el proyecto Horux Backend.

## Requisitos Previos

### Software Requerido

| Software | Version Minima | Comando de verificacion |
|----------|---------------|------------------------|
| PHP | 8.0.2 | `php -v` |
| Composer | 2.0 | `composer -V` |
| MySQL/MariaDB | 5.7 / 10.3 | `mysql --version` |
| Node.js | 16.0 | `node -v` |
| NPM | 8.0 | `npm -v` |
| Git | 2.0 | `git --version` |

### Extensiones PHP Requeridas

```
- BCMath
- Ctype
- cURL
- DOM
- Fileinfo
- JSON
- Mbstring
- OpenSSL
- PDO
- PDO_MySQL
- Tokenizer
- XML
```

Verificar extensiones instaladas:
```bash
php -m
```

---

## Instalacion Paso a Paso

### 1. Clonar Repositorio

```bash
git clone https://git.consultoria-as.com/tu-usuario/Horux_back.git
cd Horux_back
```

### 2. Instalar Dependencias PHP

```bash
composer install
```

Si hay problemas de memoria:
```bash
COMPOSER_MEMORY_LIMIT=-1 composer install
```

### 3. Instalar Dependencias NPM

```bash
npm install
```

### 4. Configurar Archivo de Entorno

```bash
# Copiar archivo de ejemplo
cp .env.example .env

# Generar clave de aplicacion
php artisan key:generate
```

### 5. Editar Configuracion

Editar el archivo `.env` con los valores apropiados:

```env
# Aplicacion
APP_NAME=Horux
APP_ENV=local
APP_KEY=base64:GENERADA_AUTOMATICAMENTE
APP_DEBUG=true
APP_URL=http://localhost:8000

# Base de Datos
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=horux360bd
DB_USERNAME=tu_usuario
DB_PASSWORD=tu_password

# Logging
LOG_CHANNEL=stack
LOG_LEVEL=debug
```

### 6. Crear Base de Datos

```bash
# Conectar a MySQL
mysql -u root -p

# Crear base de datos
CREATE DATABASE horux360bd CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# Crear usuario (opcional)
CREATE USER 'horux_user'@'localhost' IDENTIFIED BY 'password_seguro';
GRANT ALL PRIVILEGES ON horux360bd.* TO 'horux_user'@'localhost';
FLUSH PRIVILEGES;

# Salir
exit
```

### 7. Ejecutar Migraciones

```bash
php artisan migrate
```

O importar el dump existente:
```bash
mysql -u usuario -p horux360bd < horux360bd.sql
```

### 8. Configurar Laravel Passport

```bash
# Instalar Passport
php artisan passport:install

# Esto generara Client ID y Client Secret
# Copiar estos valores al archivo .env o config/app.php
```

Agregar al `.env`:
```env
PASSPORT_CLIENT_ID=1
PASSPORT_CLIENT_SECRET=XXXXXXXXXXXXXXXXXXXXX
```

### 9. Configurar Permisos de Directorios

```bash
# Linux/Mac
chmod -R 775 storage
chmod -R 775 bootstrap/cache

# Si hay problemas de permisos
sudo chown -R www-data:www-data storage bootstrap/cache
```

### 10. Compilar Assets (Opcional)

```bash
# Desarrollo
npm run dev

# Produccion
npm run build
```

### 11. Iniciar Servidor de Desarrollo

```bash
php artisan serve
```

La aplicacion estara disponible en: `http://localhost:8000`

---

## Configuracion Avanzada

### Configurar Clerk (Autenticacion)

1. Crear cuenta en [Clerk](https://clerk.com)
2. Crear aplicacion y obtener credenciales
3. Configurar redirect URIs:
   - Desarrollo: `http://localhost:3000/callback`
   - Produccion: `https://tu-dominio.com/callback`

### Configurar Syntage API

La API key de Syntage se configura en `routes/api.php`. Para produccion, mover a variables de entorno:

```env
SYNTAGE_API_KEY=tu_api_key
```

### Configurar Facturama

```env
FACTURAMA_USER=tu_usuario
FACTURAMA_PASSWORD=tu_password
FACTURAMA_SANDBOX=true  # false para produccion
```

---

## Configuracion para Produccion

### 1. Optimizar Autoloader

```bash
composer install --optimize-autoloader --no-dev
```

### 2. Cachear Configuracion

```bash
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

### 3. Configurar Variables de Produccion

```env
APP_ENV=production
APP_DEBUG=false
APP_URL=https://tu-dominio.com

LOG_LEVEL=error
```

### 4. Configurar HTTPS

Asegurarse de que el servidor web (Nginx/Apache) tenga SSL configurado.

### 5. Configurar Cola de Trabajos (Opcional)

```bash
# En .env
QUEUE_CONNECTION=database

# Ejecutar migraciones de cola
php artisan queue:table
php artisan migrate

# Iniciar worker
php artisan queue:work
```

---

## Configuracion de Servidor Web

### Nginx

```nginx
server {
    listen 80;
    server_name tu-dominio.com;
    root /var/www/Horux_back/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}
```

### Apache

Crear archivo `.htaccess` en `/public`:

```apache
<IfModule mod_rewrite.c>
    <IfModule mod_negotiation.c>
        Options -MultiViews -Indexes
    </IfModule>

    RewriteEngine On

    # Handle Authorization Header
    RewriteCond %{HTTP:Authorization} .
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

    # Redirect Trailing Slashes If Not A Folder...
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_URI} (.+)/$
    RewriteRule ^ %1 [L,R=301]

    # Send Requests To Front Controller...
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
</IfModule>
```

---

## Solucion de Problemas

### Error: SQLSTATE[HY000] [2002]

No se puede conectar a MySQL. Verificar:
- MySQL esta corriendo: `sudo systemctl status mysql`
- Credenciales en `.env` son correctas
- Host y puerto son correctos

### Error: Permission denied

```bash
sudo chown -R $USER:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache
```

### Error: Class not found

```bash
composer dump-autoload
php artisan clear-compiled
```

### Error: The Mix manifest does not exist

```bash
npm run dev
# o
npm run build
```

### Limpiar Cache

```bash
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear
```

---

## Comandos Utiles

```bash
# Ver rutas disponibles
php artisan route:list

# Ejecutar tests
php artisan test

# Ejecutar tinker (REPL)
php artisan tinker

# Crear nuevo controlador
php artisan make:controller NombreController

# Crear nuevo modelo
php artisan make:model Nombre -m

# Ver logs
tail -f storage/logs/laravel.log
```