DevOps, CI/CD Pipelines & Runbooks

1. CI/CD Pipeline & Deployment Strategies

The Alta Voce platform hosting infrastructure runs on managed Gandi Simple Hosting servers (Apache/PHP environment). Frontend and backend deployment pipelines are automated (via GitHub Actions or GitLab CI runners) executing the following workflows.

1.1. Backend Deployment (Laravel)

The deployment pipeline automates PHP file transfers and compiles production dependencies.

graph TD
    A[Code validated on main branch] --> B[GitHub Action triggered]
    B --> C[Install dependencies: composer install --no-dev]
    C --> D[Run security scanner and PHP Linter]
    D --> E[Deploy files via SFTP / Rsync to Gandi hosting]
    E --> F[Run post-deployment commands via SSH]
    F --> G[Service live and operational]

Post-Deployment Optimization Commands (Executed via SSH on Gandi):

After files have been transferred, all system caches must be cleared and rebuilt to optimize PHP request processing:

# Navigate to the production folder
cd /web/html/admin-alta

# Run database schema migrations in non-interactive force mode
php artisan migrate --force

# Rebuild configuration cache
php artisan config:cache

# Rebuild route cache (speeds up API matching routes)
php artisan route:cache

# Rebuild compiled Blade views cache
php artisan view:cache

# Rebuild event listener mappings cache
php artisan event:cache

1.2. Frontend Deployment (Vue.js 3)

As the frontend is a static Single Page Application (SPA), it is completely built inside the pipeline runner prior to deployment:

# Navigate to the web client folder
cd client-alta

# Install production dependencies
npm ci

# Compile and minify source assets for production
npm run build

The compiled static files in the dist/ directory are then transferred to the public root /web/html/client-alta on Gandi hosting.

2. Database Management Runbook

This section details manual administration steps for backup, recovery, and updates on the production MySQL backend.

2.1. Creating a Database Backup

Always export the database before running migration scripts or executing schema modifications:

# Generate a timestamped backup SQL file of the production database
mysqldump -u [user_db] -p[password_db] [name_db] > backup_altavoce_$(date +%F_%H%M%S).sql

[!WARNING] Do not leave a space between the -p parameter flag and your database password.

2.2. Restoring a Database Backup (Rollback)

In case of a critical system failure during deployment:

# Import the backup file into the clean production database schema
mysql -u [user_db] -p[password_db] [name_db] < backup_altavoce_date.sql

2.3. Safe Database Migration Guidelines

When executing migrations:

1. Prevent Table Locking: On large tables like telemetries (consisting of millions of rows), adding columns or indexes can lock database writes. Schedule schema migrations during off-peak hours (between 11:00 PM and 04:00 AM).
2. Reverting Migration Scripts: If a migration script fails midway, run:

   php artisan migrate:rollback --step=1
   

3. Incident Troubleshooting Guide

Use this troubleshooting guide to resolve common operational issues.

3.1. Incident A: HTTP 500 Server Error after deployment

• Symptoms: The Client Workspace or Admin panel returns a blank screen or a 500 Internal Server Error.
• Possible Cause: Stale or corrupted application cache files.
• Resolution: Access the backend server via SSH and manually clear all caches:

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

3.2. Incident B: Telemetries rejected with HTTP 403 / 401

• Symptoms: Desktop clients fail to submit telemetry heartbeat reports.
• Possible Cause: Revoked license key, invalid token, or expired credentials.
• Resolution:
  1. Access the Filament Admin panel (Licenses Resource) and confirm that the target group's license is active (valid = 1).
  2. Inspect PHP logs in storage/logs/laravel.log for validation decrypt failures.

3.3. Incident C: Server disk space saturation (Disk Full)

• Symptoms: Database write operations fail; API endpoints randomly return HTTP 500 errors.
• Possible Cause: Accumulated log records or verbose Telescope entries.
• Resolution:
  1. Purge old logs:

     rm storage/logs/laravel-*.log
     
  2. Prune Telescope entries:

     php artisan telescope:prune --hours=24
     
  3. Force telemetry cleanup (maintains only the 7-day retention window):

     php artisan abtest:prune-telemetry
     

3.4. Incident D: Daily BI summaries are missing on the Client Dashboard

• Symptoms: Analytics charts (Pitch F0, call durations) display empty lines for the previous day.
• Possible Cause: The nightly aggregation cron (summaries:build) failed or was interrupted.
• Resolution:
  1. Manually trigger the aggregation task:

     php artisan summaries:build
     
  2. Check CLI logs for malformed agent telemetry structures blocking the calculation scripts.