Prerrequisitos del Sistema

1. Sistema Operativo

   Requiere Linux o Unix-like OS. Windows solo funciona con WSL (Windows Subsystem for Linux).

2. Python 3.10+

   Instalar Python 3.10 o superior:

   python3 --version
   # Verificar versión mínima: 3.10+
   pip install -r requirements.txt

3. tmux instalado

   Requisito obligatorio para persistencia de sesiones:

   apt-get install tmux    # Debian/Ubuntu
   yum install tmux        # RHEL/CentOS
   dnf install tmux        # Fedora
   brew install tmux       # macOS (para WSL)

4. C compiler

   Necesario para integración tests y compilación de fixtures:

   apt-get install build-essential gcc
   yum groupinstall "Development Tools"

5. WebSocket server compatible

   Para conexiones persistentes con frontend.

Instalación Básica

1. Clonar repositorio oficial

   Obtener el código fuente desde GitHub:

   git clone https://github.com/DarranLiu/Easy-Web-Vibecoding.git
   cd Easy-Web-Vibecoding

2. Actualizar a versión estable v0.1.3+

   Fijar en release con fixes de terminal history scrolling:

   git checkout v0.1.3
   # O para última versión:
   git checkout main

3. Instalar dependencias Python

   Crear entorno virtual y activar:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

4. Configurar variables de entorno

   Establecer rutas y tokens:

   export CC_WEB_ROOTS="$HOME/projects"
   export CC_WEB_DEFAULT_DIR="$HOME/projects"
   export CC_WEB_HOST="127.0.0.1"
   export CC_WEB_PORT="8000"
   export CC_WEB_AUTH="1"

5. Ejecutar servidor web

   Arrancar backend con FastAPI:

   python -m uvicorn main:app --reload
   # O usar script incluido:
   ./run.sh

Configuración Avanzada

1. Configurar CC_WEB_TOKEN

   Generar token seguro para autenticación:

   # Generar token aleatorio de 64 caracteres
   python3 -c "import secrets; print(secrets.token_hex(32))"
   export CC_WEB_TOKEN="tu-token-aleatorio-aqui"
   chmod 0600 ~/.cc-web-token

2. Configurar CC_WEB_ROOTS

   Definir allowlist de directorios para file APIs:

   export CC_WEB_ROOTS="$HOME/projects,$HOME/code"
   # No establecer a '/' por seguridad

3. Configurar herramientas de IA

   Establecer paths a ejecutables (auto-detectados si no se especifican):

   # Claude Code
   export CC_WEB_CLAUDE="/usr/local/bin/claude"
   # Codex
   export CC_WEB_CODEX="/usr/local/bin/codex"
   # OpenCode
   export CC_WEB_OPENCODE="/usr/local/bin/opencode"

4. Configurar GPU monitoring (opcional)

   Para monitorización de recursos:

   nvidia-smi -L    # Verificar GPU disponible
   docker run --gpus all ...  # Si usas Docker

Comprobación Posterior

1. Verificar acceso al servidor

   Acceder desde navegador:

   curl http://127.0.0.1:8000
   # Debería mostrar API endpoints

2. Probar autenticación

   Verificar token en headers:

   curl -H "Authorization: Bearer TU_TOKEN" http://127.0.0.1:8000/health
   # Debería responder con estado saludable

3. Probar persistencia tmux

   Verificar que sesiones sobreviven:

   tmux list-sessions
   # Cerrar navegador y verificar sesiones siguen activas

4. Probar WebSocket

   Verificar conexión persistente:

   # Instalar wsclient para testing
   pip install websocket-client
   python3 -c "import websocket; w = websocket.create_connection('ws://127.0.0.1:8000')"

Actualización y Backup

1. Backup de sesiones tmux

   Antes de cambios mayores:

   tmux capture-pane -pS -1000 > /tmp/snapshot-$(date +%Y%m%d).txt
   # O exportar a archivo JSON:
   tmux list-sessions | xargs -I {} tmux attach-session -t {} -x 0 -y 0

2. Actualizar repositorio

   Actualizar checkout y reiniciar backend:

   git pull origin main
   git checkout v0.1.3
   # Reiniciar backend (NO delete o recreate container)
   python -m uvicorn main:app --reload

3. Refrescar navegador

   Importante: solo refresh no carga Python code nuevo:

   # En navegador:
   Ctrl+Shift+R  # Hard refresh
   # O:
   F12 → Network → Disable cache → Reload

4. Verificar WebSocket reconexión

   Confirmar que backend se reconecta correctamente:

   # Ver logs del backend:
   tail -f .venv/logs/app.log
   # Debería mostrar reconexión de WebSocket

Despliegue con Docker (Opcional)

1. Crear Dockerfile

   Archivo de construcción:

   # Dockerfile
   FROM python:3.10-slim
   WORKDIR /app
   COPY requirements.txt .
   RUN pip install -r requirements.txt
   COPY . .
   CMD ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

2. Construir imagen

   Crear y ejecutar contenedor:

   docker build -t easy-web-vibecoding .
   docker run -d \
     --name easy-web-vibecoding \
     -p 8000:8000 \
     -e CC_WEB_ROOTS="/projects" \
     -e CC_WEB_TOKEN="tu-token-seguro" \
     -v /tmp/tmux-server:/tmp/tmux-server \
     easy-web-vibecoding

3. Verificar contenedor

   Confirmar funcionamiento:

   docker logs easy-web-vibecoding
   curl http://localhost:8000/health

Seguridad y Protección

• Tokens firmados con nonce-bearing

  Expira después de 30 días — reduce ventana de ataque.

• Bearer authentication compatible

  Para API clients externos.

• Revalida working directory

  Previene ejecución en directorios incorrectos.

• Rejects unsafe names y NUL bytes

  Evita inyecciones de nombre de archivo.

• Private permissions y O_NOFOLLOW

  Seguridad por defecto para archivos creados.

• No almacena API keys de modelos

  Arquitectura segura por defecto — usuarios se autentican individualmente.

Errores Habituales y Soluciones

1. Error: tmux no encontrado

   Solución:

   apt-get install tmux
   # O verificar instalación:
   tmux -V

2. Error: WebSocket connection refused

   Solución:

   # Verificar puerto 8000 está abierto
   netstat -tlnp | grep 8000
   # O usar proxy HTTPS:
   export CC_WEB_HOST="0.0.0.0"

3. Error: Token expirado

   Solución:

   # Generar nuevo token:
   python3 -c "import secrets; print(secrets.token_hex(32))"
   export CC_WEB_TOKEN="nuevo-token"

4. Error: Sesiones tmux perdidas

   Solución:

   # Verificar container no tiene tmux server antes de reiniciar:
   tmux list-sessions
   # NO eliminar ni recrear contenedor con running tasks

5. Error: Python code no carga tras actualizar

   Solución:

   # Solo refresh no carga Python code nuevo:
   python -m uvicorn main:app --reload
   # O reiniciar servicio completo

Preguntas Frecuentes (FAQ)