Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/banredco/helpdesk/llms.txt

Use this file to discover all available pages before exploring further.

Esta guía te lleva de cero a un helpdesk completamente operativo en menos de 15 minutos. Al terminar tendrás el servidor configurado, la base de datos conectada, un administrador activo y un buzón de correo listo para recibir tickets. Sigue los pasos en orden; cada uno depende del anterior.
1

Requisitos del servidor

Antes de clonar el repositorio verifica que el servidor cumple los requisitos mínimos.
ComponenteVersión mínima
PHP8.0 o superior
MySQL5.7+ o MariaDB 10.3+
Extensiones PHPpdo_mysql, imap, mbstring, openssl
Configura un virtual host que apunte a la raíz del proyecto. A continuación se muestran ejemplos para Apache y Nginx:
Apache — VirtualHost
<VirtualHost *:80>
    ServerName helpdesk.banred.com.co
    DocumentRoot /var/www/helpdesk

    <Directory /var/www/helpdesk>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog  ${APACHE_LOG_DIR}/helpdesk-error.log
    CustomLog ${APACHE_LOG_DIR}/helpdesk-access.log combined
</VirtualHost>
Nginx — server block
server {
    listen 80;
    server_name helpdesk.banred.com.co;
    root /var/www/helpdesk;
    index index.php;

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

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}
Asegúrate también de que la extensión imap esté habilitada en php.ini:
php.ini
extension=imap
extension=pdo_mysql
extension=mbstring
extension=openssl
2

Clonar el repositorio e instalar dependencias

Clona el repositorio en el directorio raíz configurado en el paso anterior e instala la única dependencia de Composer: google/apiclient ^2.19, que habilita la integración con Gmail API.
Terminal
git clone https://github.com/banredco/helpdesk.git /var/www/helpdesk
cd /var/www/helpdesk
composer install --no-dev --optimize-autoloader
Cuando Composer termine verás el directorio vendor/ con las dependencias de Google API Client y sus bibliotecas transitivas.
3

Configurar la base de datos

Crea la base de datos y el usuario en MySQL, luego edita el archivo config/database.php con las credenciales correspondientes. El archivo ya contiene la estructura exacta que el sistema espera:
config/database.php
<?php

return [

    'host'     => 'localhost',

    'database' => 'helpdesk',

    'username' => 'helpdeskadmin',

    'password' => 'Redesjc2026*',

    'charset'  => 'utf8mb4'

];
El sistema crea la conexión PDO en config/connection.php a partir de este arreglo, fijando también la zona horaria de MySQL a America/Bogota (UTC-5):
config/connection.php (fragmento)
$pdo = new PDO(
    "mysql:host={$config['host']};dbname={$config['database']};charset={$config['charset']}",
    $config['username'],
    $config['password']
);

$pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
$pdo->exec("SET time_zone='-05:00'");
El archivo config/database.php incluido en el repositorio contiene credenciales de ejemplo (Redesjc2026*). Cambia la contraseña por una segura y única antes de exponer el servidor a cualquier red. Nunca confirmes este archivo con credenciales reales en el control de versiones.
Una vez editado el archivo, importa el esquema SQL inicial:
Terminal
mysql -u helpdeskadmin -p helpdesk < database/schema.sql
4

Configurar sesiones y acceso

El sistema de autenticación se apoya en config/auth.php, que gestiona el ciclo de vida de la sesión PHP y protege todas las rutas del panel de administración. No requiere configuración adicional para un entorno estándar: el archivo inicia la sesión si aún no existe y expone dos funciones clave:
config/auth.php
<?php

if (session_status() === PHP_SESSION_NONE) {
    session_start();
}

function isLogged()
{
    return isset($_SESSION['user_id']);
}

function requireLogin()
{
    if (!isLogged()) {
        header('Location: /admin/login.php');
        exit;
    }
}
Cada página del panel llama a requireLogin() al inicio. Si la sesión no contiene user_id, el visitante es redirigido automáticamente al formulario de inicio de sesión. Para entornos de producción se recomienda configurar session.cookie_secure = 1 y session.cookie_httponly = 1 en php.ini y servir el sitio exclusivamente sobre HTTPS.
5

Generar la contraseña del administrador

El sistema almacena las contraseñas usando password_hash() de PHP con el algoritmo PASSWORD_DEFAULT (bcrypt). El archivo generate-password.php incluido en la raíz del proyecto es una utilidad de línea de comandos que genera el hash de una contraseña para insertarla directamente en la base de datos:
generate-password.php
<?php

echo password_hash('Banred5050*', PASSWORD_DEFAULT);
Ejecuta el script desde la terminal con tu propia contraseña, copia el hash resultante e insértalo en la tabla users:
Terminal
# Genera el hash (reemplaza la contraseña por la tuya)
php -r "echo password_hash('TuContraseñaSegura2025*', PASSWORD_DEFAULT);"

# Inserta o actualiza el usuario administrador en la base de datos
mysql -u helpdeskadmin -p helpdesk -e \
  "UPDATE users SET password_hash='HASH_GENERADO' WHERE email='admin@banred.com.co';"
Si es una instalación limpia sin usuarios todavía, usa una sentencia INSERT en lugar de UPDATE para crear el primer registro de administrador con role_id = 1 e is_active = 1.
6

Primer acceso al panel

Abre el navegador y navega a la URL raíz de tu instalación (p. ej. http://helpdesk.banred.com.co). El archivo index.php ejecuta una redirección inmediata a /admin, donde el sistema detectará que no hay sesión activa y te llevará al formulario de inicio de sesión en /admin/login.php.Ingresa con el correo y la contraseña del administrador creado en el paso anterior. Tras autenticarte correctamente llegarás al dashboard principal, que muestra en tiempo real los KPIs más importantes:
KPIDescripción
Tickets AbiertosTickets con estado «Abierto»
Esperando ClienteTickets pendientes de respuesta del cliente
EscaladosTickets con estado «Escalado»
Resueltos HoyTickets resueltos en el día actual
Cerrados HoyTickets cerrados en el día actual
El dashboard también incluye el panel de cumplimiento de SLA (OK / Riesgo / Vencido), la lista de tickets que requieren atención inmediata y el ranking de rendimiento por agente.
7

Conectar un buzón de correo

Con el sistema en marcha el siguiente paso es vincular al menos un buzón de correo para que los mensajes entrantes se conviertan automáticamente en tickets. Desde el panel de administración ve a Configuración → Correos → Nuevo Correo e introduce los datos de la cuenta.
Se recomienda usar Google Workspace como tipo de buzón preferido. La integración vía Gmail API (OAuth 2.0) es más robusta que IMAP: no requiere habilitar «acceso de aplicaciones menos seguras», no caduca por inactividad y gestiona correctamente el etiquetado de mensajes leídos en el lado de Gmail. Consulta la guía completa de configuración en Buzones de Correo.
Para buzones IMAP en otros proveedores (Outlook, Zoho, servidores propios) asegúrate de que el puerto IMAP (normalmente 993 con SSL) esté abierto desde el servidor donde corre Helpdesk y de que la extensión imap de PHP esté activa, tal como se verificó en el paso 1.

Build docs developers (and LLMs) love