Installation Guide

This guide covers installing GIMA for production environments with security best practices, performance optimization, and deployment considerations.

System Requirements

Before installing GIMA, ensure your server meets these requirements:

Required Software

PHP

Version: 8.2 or higherRequired Extensions:

OpenSSL
PDO
Mbstring
Tokenizer
XML
Ctype
JSON
BCMath

PostgreSQL

Version: 12 or higherConfiguration:

UTF-8 encoding
At least 1GB allocated memory
Connection pooling recommended

Composer

Version: 2.0 or higherPHP dependency manager required for installing Laravel packages.

Node.js & npm

Version: 18 or higherRequired for compiling frontend assets with Vite.

Optional But Recommended

Web Server: Nginx or Apache with mod_rewrite
Process Manager: Supervisor for queue workers
Caching: Redis for cache and session storage
SSL Certificate: For HTTPS in production

Installation Steps

Prepare the Environment

Create a dedicated user and directory for the application:

# Create application user (optional but recommended)
sudo useradd -m -s /bin/bash gima
sudo su - gima

# Create application directory
mkdir -p /var/www/gima
cd /var/www/gima

Clone or Download GIMA

Get the GIMA source code:

git clone <repository-url> .

Install PHP Dependencies

Install Laravel and all required packages:

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

The --no-dev flag excludes development dependencies for production. For development environments, use composer install without this flag.

Key dependencies installed:

Laravel Framework 12.0
Laravel Sanctum 4.0 (API authentication)
Spatie Laravel Permission 6.23 (role management)
Laravel Tinker 2.10.1 (REPL)

Configure Environment Variables

Copy the example environment file and configure it:

cp .env.example .env
nano .env  # or use your preferred editor

Essential Configuration

Application Settings
Database Configuration
Session & Cache
Logging & Mail

.env

APP_NAME=GIMA
APP_ENV=production
APP_KEY=  # Will be generated in next step
APP_DEBUG=false
APP_URL=https://your-domain.com

APP_LOCALE=en
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=en_US

Set APP_DEBUG=false in production to prevent sensitive information disclosure.

.env

# PostgreSQL Connection
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=gima_bd
DB_USERNAME=gima_user
DB_PASSWORD=your_secure_password_here

For production, create a dedicated PostgreSQL user with limited privileges:

CREATE USER gima_user WITH PASSWORD 'your_secure_password';
CREATE DATABASE gima_bd OWNER gima_user;
GRANT ALL PRIVILEGES ON DATABASE gima_bd TO gima_user;

.env

# Session Configuration
SESSION_DRIVER=database
SESSION_LIFETIME=120
SESSION_ENCRYPT=false

# Cache Configuration
CACHE_STORE=database

# Queue Configuration
QUEUE_CONNECTION=database

GIMA uses database for sessions and cache by default. For better performance, consider using Redis:

SESSION_DRIVER=redis
CACHE_STORE=redis
QUEUE_CONNECTION=redis

.env

# Logging
LOG_CHANNEL=stack
LOG_STACK=single
LOG_LEVEL=info

# Mail Configuration (for notifications)
MAIL_MAILER=smtp
MAIL_HOST=smtp.your-provider.com
MAIL_PORT=587
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=your_email_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="${APP_NAME}"

Generate Application Key

Generate a unique encryption key for your application:

php artisan key:generate

This creates a secure random key and adds it to your .env file.

Never share your APP_KEY. If compromised, regenerate it and re-encrypt all encrypted data.

Set File Permissions

Ensure Laravel can write to storage and cache directories:

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

Adjust www-data to match your web server user (may be nginx, apache, etc.).

Create Database Tables

Run migrations to create all database tables:

php artisan migrate --force

This creates tables for:

User authentication and roles
Asset management (activos, articulos, ubicaciones)
Maintenance operations (mantenimientos, calendario_mantenimientos)
Inventory (repuestos, proveedores)
Reports and audits
Session and cache storage
Job queue

The --force flag is required in production environments. It bypasses the confirmation prompt.

Seed Roles and Permissions

Initialize the role-based access control system:

php artisan db:seed --class=RolesSeeder

This creates:Four User Roles:

admin - Full system access
supervisor - Asset and maintenance management
tecnico - Field operations
reporter - Basic reporting

Granular Permissions:

gestionar usuarios - User management (admin)
gestion maestra - Master data CRUD (admin)
gestionar activos - Asset management (supervisor)
gestionar mantenimientos - Maintenance scheduling (supervisor)
gestionar reportes - Report assignment (supervisor)
ver mis tareas - View assigned tasks (technician)
registrar actividad tecnica - Log maintenance work (technician)
registrar repuestos usados - Record parts usage (technician)
crear reporte fallas - Submit failure reports (all)
ver mis reportes - View own reports (all)
ver catalogo activos - View asset catalog (all)

Test Users Created:

Role	Name	Email	Password
Admin	Admin User	[email protected]	12345678
Supervisor	Roberto Supervisor	[email protected]	12345678
Technician	Juan Técnico	[email protected]	12345678
Reporter	Ana Reportes	[email protected]	12345678

Production Security: Delete or change passwords for test users immediately:

php artisan tinker
>>> User::where('email', '[email protected]')->delete();

Create your actual admin user with a strong password.

Compile Frontend Assets

Install Node.js dependencies and build assets:

npm install
npm run build

This compiles all frontend assets using Vite for optimal performance.

Optimize for Production

Run Laravel optimization commands:

# Cache configuration
php artisan config:cache

# Cache routes
php artisan route:cache

# Cache views
php artisan view:cache

# Optimize autoloader
composer dump-autoload --optimize

After any configuration changes in production, remember to clear and rebuild caches:

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

Then re-run the cache commands above.

Web Server Configuration

Nginx Configuration

Create a new Nginx server block:

/etc/nginx/sites-available/gima

server {
    listen 80;
    listen [::]:80;
    server_name your-domain.com;
    root /var/www/gima/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.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

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

Enable the site and reload Nginx:

sudo ln -s /etc/nginx/sites-available/gima /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Apache Configuration

Create a virtual host:

/etc/apache2/sites-available/gima.conf

<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /var/www/gima/public

    <Directory /var/www/gima/public>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/gima-error.log
    CustomLog ${APACHE_LOG_DIR}/gima-access.log combined
</VirtualHost>

Enable required modules and the site:

sudo a2enmod rewrite
sudo a2ensite gima
sudo systemctl reload apache2

Queue Worker Setup

GIMA uses Laravel queues for background jobs. Set up a queue worker with Supervisor:

Install Supervisor

sudo apt-get install supervisor

Create Supervisor Configuration

/etc/supervisor/conf.d/gima-worker.conf

[program:gima-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/gima/artisan queue:work database --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/gima/storage/logs/worker.log
stopwaitsecs=3600

Start Queue Worker

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start gima-worker:*

Scheduled Tasks (Cron)

Laravel’s task scheduler requires a single cron entry:

crontab -e

Add this line:

* * * * * cd /var/www/gima && php artisan schedule:run >> /dev/null 2>&1

This runs Laravel’s scheduler every minute, which handles all scheduled tasks defined in the application.

SSL/TLS Configuration

Secure your installation with Let’s Encrypt:

# Install Certbot
sudo apt-get install certbot python3-certbot-nginx

# Obtain and install certificate
sudo certbot --nginx -d your-domain.com

Certbot automatically configures Nginx for HTTPS and sets up auto-renewal.

Always use HTTPS in production. API tokens transmitted over HTTP can be intercepted.

Database Backup

Set up automated PostgreSQL backups:

backup.sh

#!/bin/bash
BACKUP_DIR="/var/backups/gima"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

pg_dump -U gima_user gima_bd | gzip > $BACKUP_DIR/gima_$DATE.sql.gz

# Keep only last 7 days of backups
find $BACKUP_DIR -type f -mtime +7 -delete

Schedule with cron:

0 2 * * * /path/to/backup.sh

Security Checklist

Before going live, verify these security measures:

Performance Optimization

Redis Cache (Recommended)

For better performance, use Redis for cache and sessions:

Install Redis

sudo apt-get install redis-server
sudo systemctl enable redis-server

Install PHP Redis Extension

sudo apt-get install php8.2-redis
sudo systemctl restart php8.2-fpm

Update Environment

.env

CACHE_STORE=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

Clear and Rebuild Cache

php artisan cache:clear
php artisan config:cache

Database Optimization

PostgreSQL

-- Create indexes for frequently queried columns
CREATE INDEX idx_activos_estado ON activos(estado);
CREATE INDEX idx_activos_ubicacion ON activos(ubicacion_id);
CREATE INDEX idx_mantenimientos_estado ON mantenimientos(estado);
CREATE INDEX idx_mantenimientos_activo ON mantenimientos(activo_id);
CREATE INDEX idx_calendario_fecha ON calendario_mantenimientos(fecha_programada);

-- Optimize query planner
ANALYZE;

Monitoring and Logging

Log Files Location

/var/www/gima/storage/logs/
├── laravel.log          # Application logs
├── worker.log           # Queue worker logs
└── query.log            # Database queries (if enabled)

Log Rotation

Configure logrotate:

/etc/logrotate.d/gima

/var/www/gima/storage/logs/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 www-data www-data
    sharedscripts
}

Troubleshooting

500 Internal Server Error

Check Laravel logs:

tail -f /var/www/gima/storage/logs/laravel.log

Common causes:

Incorrect file permissions on storage/ or bootstrap/cache/
Database connection failure
Missing or incorrect APP_KEY

Database Connection Failed

Verify:

# Test PostgreSQL connection
psql -U gima_user -d gima_bd -h 127.0.0.1

# Check PostgreSQL is running
sudo systemctl status postgresql

Ensure .env credentials match your database setup.

Queue Jobs Not Processing

Check queue worker status:

sudo supervisorctl status gima-worker:*

View worker logs:

tail -f /var/www/gima/storage/logs/worker.log

Restart workers:

sudo supervisorctl restart gima-worker:*

Permission Denied Errors

Reset permissions:

cd /var/www/gima
sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache

Updating GIMA

To update to a new version:

Backup

# Backup database
pg_dump -U gima_user gima_bd > backup.sql

# Backup application files
tar -czf gima_backup.tar.gz /var/www/gima

Enable Maintenance Mode

php artisan down

Pull Updates

git pull origin main

Update Dependencies

composer install --optimize-autoloader --no-dev
npm install
npm run build

Run Migrations

php artisan migrate --force

Clear and Rebuild Cache

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

Restart Services

sudo supervisorctl restart gima-worker:*
sudo systemctl reload php8.2-fpm
sudo systemctl reload nginx

Disable Maintenance Mode

php artisan up

Support Resources

Laravel Documentation

Official Laravel framework documentation

PostgreSQL Documentation

PostgreSQL database documentation

Spatie Permission

Role and permission package docs

Laravel Sanctum

API authentication documentation

Your GIMA installation is now complete and ready for production use!

Get Started

Core Concepts

Guides

Installation

Installation Guide

System Requirements

Required Software

PHP

PostgreSQL

Composer

Node.js & npm

Optional But Recommended

Installation Steps

Essential Configuration

Web Server Configuration

Nginx Configuration

Apache Configuration

Queue Worker Setup

Scheduled Tasks (Cron)

SSL/TLS Configuration

Database Backup

Security Checklist

Performance Optimization

Redis Cache (Recommended)

Database Optimization

Monitoring and Logging

Log Files Location

Log Rotation

Troubleshooting

Updating GIMA

Support Resources

Laravel Documentation

PostgreSQL Documentation

Spatie Permission

Laravel Sanctum

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Installation Guide

​System Requirements

​Required Software

PHP

PostgreSQL

Composer

Node.js & npm

​Optional But Recommended

​Installation Steps

​Essential Configuration

​Web Server Configuration

​Nginx Configuration

​Apache Configuration

​Queue Worker Setup

​Scheduled Tasks (Cron)

​SSL/TLS Configuration

​Database Backup

​Security Checklist

​Performance Optimization

​Redis Cache (Recommended)

​Database Optimization

​Monitoring and Logging

​Log Files Location

​Log Rotation

​Troubleshooting

​Updating GIMA

​Support Resources

Laravel Documentation

PostgreSQL Documentation

Spatie Permission

Laravel Sanctum

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Required Software

Optional But Recommended

Installation Steps

Essential Configuration

Web Server Configuration

Nginx Configuration

Apache Configuration

Queue Worker Setup

Scheduled Tasks (Cron)

SSL/TLS Configuration

Database Backup

Security Checklist

Performance Optimization

Redis Cache (Recommended)

Database Optimization

Monitoring and Logging

Log Files Location

Log Rotation

Troubleshooting

Updating GIMA

Support Resources