Guía de despliegue local

1. Arquitectura de destino

TranscribIA local se basa en una infraestructura Docker Compose autónoma que orquesta servicios de aplicación y bases de datos en un mismo host (o distribuidos según su infraestructura). La transcripción, que requiere gran capacidad de cálculo, se realiza en un servidor GPU externo dedicado.

El servidor de transcripción GPU (motores WhisperX y pyannote, ejecución CUDA) es un componente separado conectado al resto de la infraestructura. Puede compartir el host GPU o estar aislado en un servidor dedicado según su topología de red.

2. Requisitos de hardware

Servidor de aplicaciones

Servidor de transcripción — GPU

La transcripción y la diarización se ejecutan con un acelerador gráfico. Se admiten dos familias de hardware:

3. Requisitos de software

4. Etapas de instalación

El repositorio proporciona un Makefile y un .env.example. El procedimiento estándar se realiza con unos pocos comandos:

git clone <repo-transcribia> transcribia
cd transcribia

# 2. Préparer le fichier d'environnement
cp .env.example .env
#   → renseigner DB_PASSWORD, REDIS_PASSWORD, clés IA…

# 3. Installation complète
#    (build images + dépendances Composer/NPM + migrations + seed)
make install

# ── ou, étape par étape ──────────────────────
docker compose build
docker compose up -d
docker compose exec app php artisan key:generate
docker compose exec app php artisan migrate
docker compose exec app php artisan db:seed

Objetivos útiles: make up, make down, make restart, make logs, make migrate, make seed.

5. Configuración (.env)

Las siguientes variables controlan la base de datos, la caché y los motores de IA. En modo 100 % local, se activa el LLM local y se deja vacía la clave de la nube:

# ── Base de données PostgreSQL ──────────────
DB_DATABASE=transcribia
DB_USERNAME=transcribia
DB_PASSWORD=<mot-de-passe-fort>

# ── Redis (cache + queues + sessions) ────────
REDIS_PASSWORD=<mot-de-passe-fort>

# ── Moteurs IA ───────────────────────────────
ALLOW_LOCAL_LLM=true
LLM_BASE_URL=http://llm-local:8000/v1     # serveur LLM local
OPENROUTER_API_KEY=                         # vide en full on-premise

ALLOW_LOCAL_LLM redirige la generación (resúmenes, actas, etc.) al endpoint local declarado en LLM_BASE_URL. Mientras OPENROUTER_API_KEY permanezca vacía, ninguna llamada de IA saldrá de su infraestructura.

6. Modo air-gap (sin conexión)

Para entornos sin acceso a Internet, TranscribIA funciona completamente desconectado tomando tres precauciones:

• Modelos descargados previamente : los modelos WhisperX y pyannote (y los posibles LLM locales) se descargan de Hugging Face en un equipo conectado y después se transfieren al servidor de destino.
• Imágenes Docker disponibles localmente : las imágenes se cargan desde un archivo (docker load) en lugar de descargarse de un registro público.
• Actualizaciones manuales : las nuevas versiones se aplican mediante transferencia de paquetes, sin git pull ni docker pull en línea.

export HF_HUB_OFFLINE=1   # Hugging Face : pas d'accès réseau
export TRANSFORMERS_OFFLINE=1

7. Primer inicio y verificación

Cada servicio de docker-compose.yml expone una comprobación de estado. Comprobación posterior al inicio:

docker compose ps                       # tous les services "healthy"
docker compose exec app php artisan migrate:status
curl -fsS http://localhost:3480/        # page d'accueil (HTTP 200)
docker compose logs -f app              # journaux applicatifs

Un servicio que no alcanza el estado healthy suele indicar que falta una variable de entorno (DB / Redis) o que no se detecta la GPU en el servidor de transcripción.

8. Actualizaciones y mantenimiento

# Récupérer la nouvelle version
git pull

# Reconstruire + migrer
make install

# Redémarrer proprement
docker compose up -d

• Copias de seguridad : programar volcados PostgreSQL regulares y la copia del volumen storage/ (archivos de audio, exportaciones), preferiblemente en otra ubicación.
• Rotación de registros : gestionada por Docker (json-file, 10 MB × 3 archivos por servicio).
• Parches : AMBASSADIA SARL proporciona las actualizaciones de seguridad, aplicables con el mismo procedimiento.

9. Supervisión

• Estado de los contenedores : docker compose ps y comprobaciones de estado integradas.
• Registros de la aplicación : docker compose logs -f app (Laravel); registros estructurados en storage/logs.
• Colas : seguimiento de los workers queue, queue-ai, queue-media mediante Redis.
• GPU : nvidia-smi -l 5 para la carga y la VRAM del servidor de transcripción.
• Métricas : exportación posible a sus herramientas de supervisión actuales (Prometheus/Grafana, etc.) bajo petición.

10. Responsabilidades — cliente y Transcribia

Reparto orientativo de responsabilidades operativas en un despliegue local:

El reparto preciso de roles y los SLA correspondientes se formalizan en el contrato de soporte y el DPA de instalación local. Esta guía no sustituye a dichos documentos contractuales.