llm-server-setup/README.md

# LLM Server

Despliegue automatizado de un servidor LLM local con Ollama, LiteLLM y
OpenClaw sobre Ubuntu 22.04/24.04.

## Requisitos

- Ubuntu 22.04 o 24.04
- CPU de 4 núcleos o superior
- 16 GB de RAM como mínimo
- GPU NVIDIA compatible con sus controladores Linux
- Acceso `sudo` y conexión a Internet

La configuración está orientada a una NVIDIA RTX 3090 de 24 GB, pero el
script puede utilizarse con otras GPU compatibles ajustando el modelo si es
necesario.

## Instalación

Clona el repositorio en el servidor:

```bash
git clone https://gitea.oemspot.com.ar/carlostellocba/llm-server-setup.git
cd llm-server-setup
```

Ejecuta el instalador principal como `root` o mediante `sudo`:

```bash
chmod +x setup_llm_server.sh
sudo ./setup_llm_server.sh
```

El instalador:

- actualiza los paquetes del sistema e instala dependencias;
- configura un archivo de swap de 8 GB;
- instala los controladores NVIDIA si no están disponibles;
- instala y configura Ollama en `0.0.0.0:11434`;
- crea un entorno virtual de LiteLLM en `/opt/litellm-env`;
- descarga `qwen2.5-coder:14b`;
- crea el servicio `litellm.service` en el puerto `8000`;
- permite SSH y LiteLLM mediante UFW.

El proceso puede tardar varios minutos y requiere espacio suficiente para el
modelo. Si se instalan controladores NVIDIA nuevos, reinicia el servidor:

```bash
sudo reboot
```

## Verificación

Después de la instalación, comprueba los servicios:

```bash
systemctl status ollama
systemctl status litellm
nvidia-smi
curl http://127.0.0.1:11434/api/tags
curl http://127.0.0.1:8000/health/liveliness
```

La configuración de LiteLLM se genera en el directorio personal del usuario
que ejecuta `sudo` y queda guardada como `~/litellm_config.yaml`.

## Instalación de OpenClaw

Para la configuración completa de OpenClaw con el servidor local, consulta
[OPENCLAW_LOCAL_SERVER.md](OPENCLAW_LOCAL_SERVER.md).

El script `install_openclaw.sh` utiliza el instalador oficial de OpenClaw y
está pensado para Linux y WSL2. Para instalarlo sin abrir el asistente inicial:

```bash
bash install_openclaw.sh
```

Para instalarlo y ejecutar el asistente inmediatamente:

```bash
bash install_openclaw.sh --onboard
```

Si la instalación se hizo sin asistente, puedes iniciarlo después y configurar
el servicio de Gateway:

```bash
openclaw onboard --install-daemon
```

Comprueba la instalación con:

```bash
openclaw --version
openclaw doctor
openclaw gateway status
```

Para acceder al dashboard desde Windows mediante PowerShell, usa un túnel SSH
hacia el servidor Ubuntu:

```powershell
ssh -N -L 18789:127.0.0.1:18789 ctello@192.168.0.225
```

Mantén la sesión abierta y entra desde el navegador en:

```text
http://127.0.0.1:18789
```

La guía completa de acceso desde PuTTY, PowerShell y solución de problemas está
en [OPENCLAW_LOCAL_SERVER.md](OPENCLAW_LOCAL_SERVER.md).

## Respaldo y recuperación

Para ejecutar un diagnóstico independiente y de solo lectura del servidor usa
`ubuntu_server_diagnostic.sh`. Comprueba Ubuntu, hardware, servicios, puertos,
Ollama, LiteLLM, OpenClaw y UFW:

```bash
chmod +x ubuntu_server_diagnostic.sh
sudo ./ubuntu_server_diagnostic.sh --report /tmp/ubuntu-server-test.txt
```

Puedes cambiar los endpoints o el modelo esperado mediante variables de entorno:

```bash
OLLAMA_URL=http://127.0.0.1:11434 \
LITELLM_URL=http://127.0.0.1:8000 \
MODEL_NAME=qwen2.5-coder:14b \
sudo -E ./ubuntu_server_diagnostic.sh
```

Para guardar la configuración del servidor antes de realizar cambios, ejecuta
el script como `root`:

```bash
chmod +x backup_ubuntu_config.sh restore_ubuntu_config.sh
sudo ./backup_ubuntu_config.sh
```

El respaldo se guarda por defecto en `/var/backups` e incluye inventario de
hardware, paquetes, servicios, red, UFW, systemd, NVIDIA, Ollama, LiteLLM,
OpenClaw y configuraciones de usuario. No incluye modelos Ollama, el entorno
virtual de LiteLLM, bases de datos ni logs completos.

Las claves SSH, certificados privados y credenciales de OpenClaw quedan fuera
por defecto. Para incluirlos explícitamente, protege el archivo resultante:

```bash
sudo ./backup_ubuntu_config.sh --include-secrets
sudo chmod 600 /var/backups/ubuntu-config-*.tar.gz
```

En una instalación Ubuntu nueva, instala primero el sistema base y crea los
usuarios necesarios. Después copia el archivo de respaldo y usa el restaurador
en modo vista previa:

```bash
sudo ./restore_ubuntu_config.sh /ruta/al/respaldo.tar.gz
```

Para aplicar la configuración:

```bash
sudo ./restore_ubuntu_config.sh /ruta/al/respaldo.tar.gz --yes
```

Puedes reinstalar los paquetes APT y arrancar los servicios habilitados de la
máquina original de forma explícita:

```bash
sudo ./restore_ubuntu_config.sh /ruta/al/respaldo.tar.gz \
  --yes --install-packages --start-services
```

Revisa siempre los servicios y el firewall después de restaurar:

```bash
systemctl --failed
systemctl status ollama litellm
sudo ufw status verbose
nvidia-smi
```

## Tool calling y rutas de Windows

Cuando un modelo envía rutas de Windows dentro de argumentos JSON, las barras
invertidas deben estar escapadas. Por ejemplo:

```json
{
  "path": "C:\\Users\\name\\file.txt"
}
```

Si las barras no están escapadas, el parser JSON puede fallar antes de que la
herramienta llegue a ejecutarse.

## Archivos principales

- `setup_llm_server.sh`: instala y configura Ollama, LiteLLM, NVIDIA y UFW.
- `install_openclaw.sh`: instala OpenClaw mediante el instalador oficial.
- `litellm_config.yaml`: configuración local opcional para LiteLLM.
- `tool_call_demo.py`: ejemplo local de manejo de llamadas a herramientas.

## Seguridad

El instalador expone Ollama en todas las interfaces y abre el puerto `8000`
en UFW. En un servidor conectado a Internet, limita esos puertos a la red
privada o protégelos detrás de un proxy con autenticación y HTTPS.