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:

php -m

---

Instalacion Paso a Paso

1. Clonar Repositorio

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

2. Instalar Dependencias PHP

composer install

Si hay problemas de memoria:

COMPOSER_MEMORY_LIMIT=-1 composer install

3. Instalar Dependencias NPM

npm install

4. Configurar Archivo de Entorno

# 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:

# 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

# 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

php artisan migrate

O importar el dump existente:

mysql -u usuario -p horux360bd < horux360bd.sql

8. Configurar Laravel Passport

# 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:

PASSPORT_CLIENT_ID=1
PASSPORT_CLIENT_SECRET=XXXXXXXXXXXXXXXXXXXXX

9. Configurar Permisos de Directorios

# 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)

# Desarrollo
npm run dev

# Produccion
npm run build

11. Iniciar Servidor de Desarrollo

php artisan serve

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

---

Configuracion Avanzada

Configurar Clerk (Autenticacion)

1. Crear cuenta en Clerk
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:

SYNTAGE_API_KEY=tu_api_key

Configurar Facturama

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

---

Configuracion para Produccion

1. Optimizar Autoloader

composer install --optimize-autoloader --no-dev

2. Cachear Configuracion

php artisan config:cache
php artisan route:cache
php artisan view:cache

3. Configurar Variables de Produccion

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)

# 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

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:

<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

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

Error: Class not found

composer dump-autoload
php artisan clear-compiled

Error: The Mix manifest does not exist

npm run dev
# o
npm run build

Limpiar Cache

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

---

Comandos Utiles

# 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