On-premise deployment guide

1. Target architecture

TranscribIA on-premise uses a standalone Docker Compose stack, orchestrating application services and databases on the same host (or distributed according to your infrastructure). Compute-intensive transcription runs on a dedicated external GPU server .

The GPU transcription server (engines WhisperX and pyannote, CUDA execution) is a separate component connected to the rest of the stack. It can share the GPU host or run on a dedicated server depending on your network topology.

2. Hardware requirements

Application server

Transcription server — GPU

Transcription and diarisation run on graphics accelerators. Two hardware families are supported:

3. Software requirements

4. Installation steps

The repository provides a Makefile and a .env.example. The standard procedure takes just a few commands:

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

Useful targets: make up, make down, make restart, make logs, make migrate, make seed.

5. Configuration (.env)

The following variables control the database, cache and AI engines. In 100% on-premisemode, enable the local LLM and leave the cloud key empty:

# ── 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 switches generation (summaries, formal documents, etc.) to your local endpoint declared through LLM_BASE_URL. As long as OPENROUTER_API_KEY remains empty, no AI request leaves your infrastructure.

6. Air-gapped mode (offline)

For environments without Internet access, TranscribIA runs fully disconnected with three precautions:

• Pre-downloaded models : WhisperX and pyannote models (and any local LLMs) are downloaded from Hugging Face on a connected workstation, then transferred to the target server.
• Locally available Docker images : images are loaded from an archive (docker load) rather than pulled from a public registry.
• Manual updates : upgrades are applied by transferring packages, without git pull or docker pull online.

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

7. First launch & verification

Each service in the docker-compose.yml exposes a healthcheck. Post-startup verification:

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

A service that does not reach the healthy state generally indicates a missing environment variable (DB / Redis) or an undetected GPU on the transcription server.

8. Updates & maintenance

# Récupérer la nouvelle version
git pull

# Reconstruire + migrer
make install

# Redémarrer proprement
docker compose up -d

• Backups : schedule regular PostgreSQL dumps and back up the storage/ volume (audio files, exports) — preferably off-site.
• Log rotation : managed by Docker (json-file, 10 MB × 3 files per service).
• Patches : security updates are delivered by AMBASSADIA SARL and applied using the same procedure.

9. Monitoring

• Container status : docker compose ps and built-in healthchecks.
• Application logs : docker compose logs -f app (Laravel); structured logs in storage/logs.
• Queues : monitor workers queue, queue-ai, queue-media through Redis.
• GPU : nvidia-smi -l 5 for transcription server load and VRAM.
• Metrics : export to your existing monitoring system (Prometheus/Grafana, etc.) available on request.

10. Responsibilities — customer vs Transcribia

Indicative allocation of operational responsibilities for an on-premise deployment:

The exact allocation of roles and associated SLAs are formalised in the support contract and on-premise DPA. This guide does not replace those contractual documents.