Operations Guide

This guide covers deployment, configuration, and maintenance.

Configuration Reference (.env)

AuditorIA requires several environment variables for different components.

Variable	Description	Default
`POSTGRES_DB`	Database Name	`auditoria_db`
`POSTGRES_USER`	Database User	`root`
`POSTGRES_PASSWORD`	Database Password	`password`
`TZ`	Timezone	`America/Argentina/Buenos_Aires`
`MINIO_ROOT_USER`	MinIO Admin User	`minioadmin`
`MINIO_ROOT_PASSWORD`	MinIO Admin Password	`minioadmin`
`KEYCLOAK_ADMIN`	Keycloak Admin User	`admin`
`KEYCLOAK_ADMIN_PASSWORD`	Keycloak Admin Password	`admin`

Variable	Description	Default/Example
`DB_URL`	Internal DB Connection String	`postgresql://root:password@whisperx_postgres:5432/auditoria_db`
`WHISPER_MODEL`	AI Model Size	`large-v3`
`DEFAULT_LANG`	Default Transcription Lang	`es`
`HF_TOKEN`	Hugging Face Token (Diarization)	`hf_...`
`OPENAI_API_KEY`	OpenAI Key (Generative AI)	`sk-...`
`KEYCLOAK_SERVER_URL`	Internal Keycloak URL	`http://keycloak:8080`
`KEYCLOAK_REALM`	Keycloak Realm	`auditoria`
`KEYCLOAK_CLIENT_ID`	Keycloak Client Resource	`Auditoria`
`KEYCLOAK_CLIENT_SECRET`	Client Secret	`your_secret`
`MINIO_URL`	Internal MinIO URL	`http://minio:9000`

Variable	Description
`NEXT_PUBLIC_API_URL`	Public API URL
`NEXT_PUBLIC_KEYCLOAK_URL`	Public Keycloak URL
`NEXT_PUBLIC_KEYCLOAK_REALM`	Public Realm Name
`NEXT_PUBLIC_KEYCLOAK_CLIENT_ID`	Client ID
`NEXT_PUBLIC_POSTHOG_KEY`	Analytics Key (Optional)
`GRAFANA_URL`	Embed URL for Analytics

We recommend using the provided docker-compose.yml as a base for Kubernetes manifests. Ensure Persistence for:

In production, place Nginx in front of the services to handle SSL termination and path routing.

Symptom: Backend logs show ConnectionRefusedError when uploading.
Cause: The container cannot reach minio:9000.
Fix: Check that auditoria_backend and minio are on the same Docker network. Ensure MINIO_URL is set to http://minio:9000 (internal) and not localhost.

Symptom: Worker relies on CPU, transcription is slow.
Fix: Ensure nvidia-container-toolkit is installed on the host and the worker service has deploy: resources: reservations: devices: - driver: nvidia configured.

Symptom: Keycloak fails to start with "Duplicate resource" error.
Cause: Conflict between realm-export.json and Keycloak's default initialization of service accounts.
Fix:
1. Stop services: docker-compose down -v (Warning: Deletes data volume).
2. Set serviceAccountsEnabled: false in realm-export.json.
3. Restart: docker-compose up -d --build.

Symptom: Backend loops waiting for database.
Cause: Postgres container is unhealthy or waiting for initialization.
Fix: Check docker logs whisperx_postgres. Ensure the healthcheck in docker-compose.yml is passing.

Symptom: "Internal Server Error" after Keycloak redirect.
Cause: Mismatch in KEYCLOAK_CLIENT_SECRET between Frontend and Keycloak, or incorrect NEXT_PUBLIC_API_URL.
Fix: Verify secrets in .env match the Keycloak Client Credentials.