cbc2027/docs/SETUP.md

Guia de Configuracion - CBCFacil

Esta guia describe los pasos para configurar el entorno de desarrollo de CBCFacil.

Requisitos Previos

Software Requerido

Componente	Version Minima	Recomendada
Python	3.10	3.11+
Git	2.0	Latest
NVIDIA Driver	535+	550+ (para CUDA 12.1)
Docker	24.0	25.0+ (opcional)
Docker Compose	2.20	Latest (opcional)

Hardware Recomendado

• CPU: 4+ nucleos
• RAM: 8GB minimum (16GB+ recomendado)
• GPU: NVIDIA con 4GB+ VRAM (opcional, soporta CPU)
• Almacenamiento: 10GB+ libres

Instalacion Paso a Paso

1. Clonar el Repositorio

git clone <repo_url>
cd cbcfacil

2. Crear Entorno Virtual

# Crear venv
python3 -m venv .venv

# Activar (Linux/macOS)
source .venv/bin/activate

# Activar (Windows)
.venv\Scripts\activate

3. Instalar Dependencias

# Actualizar pip
pip install --upgrade pip

# Instalar dependencias de produccion
pip install -r requirements.txt

# Instalar dependencias de desarrollo (opcional)
pip install -r requirements-dev.txt

4. Configurar Variables de Entorno

# Copiar template de configuracion
cp .env.example .env.secrets

# Editar con tus credenciales
nano .env.secrets

5. Estructura de Archivos Necesaria

# Crear directorios requeridos
mkdir -p downloads resumenes_docx logs

# Verificar estructura
ls -la

Configuracion de Credenciales

Nextcloud/WebDAV

# Obligatorio para sincronizacion de archivos
NEXTCLOUD_URL=https://tu-nextcloud.com/remote.php/webdav
NEXTCLOUD_USER=tu_usuario
NEXTCLOUD_PASSWORD=tu_contrasena

AI Providers (Opcional)

# Claude via Z.ai
ANTHROPIC_AUTH_TOKEN=sk-ant-...

# Google Gemini
GEMINI_API_KEY=AIza...

# Gemini CLI (opcional)
GEMINI_CLI_PATH=/usr/local/bin/gemini

Telegram (Opcional)

TELEGRAM_TOKEN=bot_token
TELEGRAM_CHAT_ID=chat_id

GPU Configuration (Opcional)

# Usar GPU especifica
CUDA_VISIBLE_DEVICES=0

# Usar todas las GPUs
CUDA_VISIBLE_DEVICES=all

# Forzar CPU
CUDA_VISIBLE_DEVICES=

Verificacion de Instalacion

1. Verificar Python

python --version
# Debe mostrar Python 3.10+

2. Verificar Dependencias

python -c "import torch; print(f'PyTorch: {torch.__version__}')"
python -c "import flask; print(f'Flask: {flask.__version__}')"
python -c "import whisper; print('Whisper instalado correctamente')"

3. Verificar Configuracion

python -c "from config import settings; print(f'WebDAV configurado: {settings.has_webdav_config}')"
python -c "from config import settings; print(f'AI configurado: {settings.has_ai_config}')"

4. Test Rapido

# Ejecutar tests basicos
pytest tests/test_config.py -v

Configuracion de Desarrollo

IDE Recomendado

VS Code

// .vscode/settings.json
{
    "python.defaultInterpreterPath": ".venv/bin/python",
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": true,
    "editor.formatOnSave": true,
    "python.formatting.provider": "black"
}

PyCharm

1. Open Settings > Project > Python Interpreter
2. Add Interpreter > Existing Environment
3. Select .venv/bin/python

Git Hooks (Opcional)

# Instalar pre-commit
pip install pre-commit
pre-commit install

# Verificar hooks
pre-commit run --all-files

Formateo de Codigo

# Instalar formateadores
pip install black isort

# Formatear codigo
black .
isort .

# Verificar estilo
black --check .
isort --check-only .

Ejecucion del Servicio

Modo Desarrollo

# Activar entorno virtual
source .venv/bin/activate

# Ejecutar servicio completo
python main.py

# Con logging verbose
LOG_LEVEL=DEBUG python main.py

Comandos CLI Disponibles

# Transcribir audio
python main.py whisper <archivo_audio> <directorio_output>

# Procesar PDF
python main.py pdf <archivo_pdf> <directorio_output>

Dashboard

El dashboard estara disponible en:

• URL: http://localhost:5000
• API: http://localhost:5000/api/

Solucion de Problemas Comunes

Error: "Module not found"

# Verificar que el venv esta activado
which python
# Debe mostrar path hacia .venv/bin/python

# Reinstalar dependencias
pip install -r requirements.txt

Error: "CUDA out of memory"

# Reducir uso de GPU
export CUDA_VISIBLE_DEVICES=

# O usar solo una GPU
export CUDA_VISIBLE_DEVICES=0

Error: "WebDAV connection failed"

# Verificar credenciales
echo $NEXTCLOUD_URL
echo $NEXTCLOUD_USER

# Probar conexion manualmente
curl -u $NEXTCLOUD_USER:$NEXTCLOUD_PASSWORD $NEXTCLOUD_URL

Error: "Telegram token invalid"

# Verificar token con BotFather
# https://t.me/BotFather

# Verificar variables de entorno
echo $TELEGRAM_TOKEN
echo $TELEGRAM_CHAT_ID

Error: "Whisper model not found"

# El modelo se descarga automaticamente la primera vez
# Para forzar recarga:
rm -rf ~/.cache/whisper

Configuracion de GPU (Opcional)

Verificar Instalacion de CUDA

# Verificar drivers NVIDIA
nvidia-smi

# Verificar CUDA Toolkit
nvcc --version

# Verificar PyTorch CUDA
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"

Configurar Memoria GPU

# En .env.secrets
PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512

Variables de Entorno Completa

Variable	Requerido	Default	Descripcion
NEXTCLOUD_URL	Si	-	URL WebDAV de Nextcloud
NEXTCLOUD_USER	Si	-	Usuario Nextcloud
NEXTCLOUD_PASSWORD	Si	-	Contrasena Nextcloud
ANTHROPIC_AUTH_TOKEN	No	-	Token Claude/Z.ai
GEMINI_API_KEY	No	-	API Key Gemini
TELEGRAM_TOKEN	No	-	Token Bot Telegram
TELEGRAM_CHAT_ID	No	-	Chat ID Telegram
CUDA_VISIBLE_DEVICES	No	"all"	GPUs a usar
POLL_INTERVAL	No	5	Segundos entre polls
LOG_LEVEL	No	"INFO"	Nivel de logging
DEBUG	No	false	Modo debug
DASHBOARD_PORT	No	5000	Puerto del dashboard
DASHBOARD_HOST	No	"0.0.0.0"	Host del dashboard

Siguientes Pasos

1. Verificar instalacion con tests
2. Configurar integracion con Nextcloud
3. Probar procesamiento de archivos
4. Configurar notificaciones Telegram (opcional)

Ver juga:

• docs/TESTING.md - Guia de testing
• docs/DEPLOYMENT.md - Guia de despliegue
• ARCHITECTURE.md - Documentacion arquitectonica