Guia de instalação local

1. Arquitetura de destino

O TranscribIA em instalação local assenta numa infraestrutura Docker Compose autónoma, que orquestra os serviços da aplicação e as bases de dados num único servidor (ou distribuídos segundo a sua infraestrutura). A transcrição, intensiva em computação, é confiada a um servidor GPU externo dedicado.

O servidor GPU de transcrição (motores WhisperX e pyannote, execução CUDA) é um componente separado, interligado com o resto da infraestrutura. Pode estar no mesmo servidor GPU ou isolado num servidor dedicado, consoante a topologia de rede.

2. Requisitos de hardware

Servidor da aplicação

Servidor de transcrição — GPU

A transcrição e a diarização são executadas num acelerador gráfico. São suportadas duas famílias de hardware:

3. Requisitos de software

4. Etapas de instalação

O repositório fornece um Makefile e um .env.example. O procedimento habitual resume-se a alguns 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

Alvos úteis: make up, make down, make restart, make logs, make migrate, make seed.

5. Configuração (.env)

As variáveis seguintes controlam a base de dados, a cache e os motores de IA. Em modo 100% instalação local, ativa-se o LLM local e deixa-se a chave cloud vazia:

# ── 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 direciona a geração (resumos, documentos, etc.) para o seu endpoint local definido por LLM_BASE_URL. Enquanto OPENROUTER_API_KEY permanecer vazia, nenhuma chamada de IA sai da sua infraestrutura.

6. Modo air-gap (sem ligação)

Para ambientes sem acesso à Internet, o TranscribIA funciona totalmente desligado mediante três precauções:

• Modelos descarregados previamente : os modelos WhisperX e pyannote (e eventuais LLM locais) são obtidos no Hugging Face num computador com ligação e depois transferidos para o servidor de destino.
• Imagens Docker locais : as imagens são carregadas a partir de um arquivo (docker load) em vez de serem obtidas num registo público.
• Atualizações manuais : as novas versões são aplicadas através da transferência de pacotes, sem git pull nem docker pull em linha.

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

7. Primeiro arranque e verificação

Cada serviço do docker-compose.yml disponibiliza uma verificação de estado (healthcheck). Verificação após o arranque:

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

Um serviço que não atinja o estado healthy indica geralmente uma variável de ambiente em falta (DB / Redis) ou uma GPU não detetada no servidor de transcrição.

8. Atualizações e manutenção

# Récupérer la nouvelle version
git pull

# Reconstruire + migrer
make install

# Redémarrer proprement
docker compose up -d

• Cópias de segurança : agendar exportações regulares do PostgreSQL e cópias de segurança do volume storage/ (ficheiros de áudio, exportações) — de preferência num local externo.
• Rotação de registos : gerida pelo Docker (json-file, 10 MB × 3 ficheiros por serviço).
• Correções : as atualizações de segurança são fornecidas pela AMBASSADIA SARL e podem ser aplicadas pelo mesmo procedimento.

9. Monitorização

• Estado dos contentores : docker compose ps e verificações de estado integradas.
• Registos da aplicação : docker compose logs -f app (Laravel); registos estruturados em storage/logs.
• Filas de espera : acompanhamento dos workers queue, queue-ai, queue-media através de Redis.
• GPU : nvidia-smi -l 5 para a carga e a VRAM do servidor de transcrição.
• Métricas : exportação possível para a sua monitorização existente (Prometheus/Grafana, etc.), mediante pedido.

10. Responsabilidades — cliente e Transcribia

Repartição indicativa das responsabilidades operacionais numa instalação local:

A repartição exata de funções e os SLA associados são formalizados no contrato de suporte e no DPA de instalação local. Este guia não substitui esses documentos contratuais.