From fbbd3ed50ca32ad83c4fdcb7468d819c59675e38 Mon Sep 17 00:00:00 2001 From: Luca Sacchi Ricciardi Date: Mon, 6 Apr 2026 18:31:57 +0200 Subject: [PATCH] docs: enhance local LLM providers documentation with network setup Expand SKILL.md LLM Providers section with comprehensive network configuration: New Sections: - Configurazione URL Personalizzato: Table of scenarios (localhost, LAN, VPN, Docker) - Setup Ollama per Rete: 3 configuration options (env var, systemd, docker) - Setup LM Studio per Rete: Step-by-step with CORS configuration - Architetture Comuni: ASCII diagrams for common setups * Server AI dedicato * Multi-client configuration * VPN Remote access - Sicurezza & Firewall: UFW and iptables rules - SSH Tunnel: Secure alternative to direct exposure - Troubleshooting Rete: Common issues and solutions Security Notes: - Warning about exposing to public IP - Firewall rules for LAN-only access - SSH tunnel as secure alternative Examples: - Docker deployment - WireGuard VPN setup - Multi-user configurations - CORS troubleshooting This documentation enables users to deploy Ollama/LM Studio on dedicated servers and access from multiple clients. --- SKILL.md | 170 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 167 insertions(+), 3 deletions(-) diff --git a/SKILL.md b/SKILL.md index 34a140f..90856f2 100644 --- a/SKILL.md +++ b/SKILL.md @@ -683,14 +683,178 @@ curl -X POST http://localhost:8000/api/v1/query \ }' ``` -#### Configurazione URL Personalizzato +#### Configurazione URL Personalizzato (IP/Hostname) -Per usare Ollama/LM Studio su un'altra macchina nella rete: +Di default, Ollama e LM Studio sono configurati per `localhost`, ma puoi usarli su **qualsiasi IP o hostname** nella tua rete. +##### Opzioni di Configurazione + +| Scenario | URL Esempio | Configurazione | +|----------|-------------|----------------| +| **Stessa macchina** | `http://localhost:11434` | Default | +| **Rete locale** | `http://192.168.1.100:11434` | IP statico | +| **Hostname** | `http://ai-server.local:11434` | mDNS/Bonjour | +| **VPN** | `http://10.8.0.5:11434` | WireGuard/OpenVPN | +| **Docker** | `http://host.docker.internal:11434` | Container | + +**File `.env`:** ```env -# .env +# Esempi di configurazione OLLAMA_BASE_URL=http://192.168.1.100:11434 LMSTUDIO_BASE_URL=http://192.168.1.50:1234 + +# Oppure con hostname +OLLAMA_BASE_URL=http://ai-server.local:11434 + +# VPN/Remoto +OLLAMA_BASE_URL=http://10.8.0.5:11434 +``` + +##### Setup Ollama per Rete (Multi-utente) + +Di default Ollama accetta solo connessioni localhost. Per abilitare altri IP: + +**Opzione 1: Variabile d'ambiente (temporanea)** +```bash +export OLLAMA_HOST=0.0.0.0:11434 +ollama serve +``` + +**Opzione 2: Systemd (permanente)** +```bash +# Crea override per il servizio +sudo systemctl edit ollama.service + +# Aggiungi: +[Service] +Environment="OLLAMA_HOST=0.0.0.0:11434" + +# Riavvia +sudo systemctl daemon-reload +sudo systemctl restart ollama +``` + +**Opzione 3: Docker** +```bash +docker run -d \ + -v ollama:/root/.ollama \ + -p 0.0.0.0:11434:11434 \ + -e OLLAMA_HOST=0.0.0.0 \ + --name ollama \ + ollama/ollama +``` + +**Verifica connessione esterna:** +```bash +# Dal client (altra macchina) +curl http://192.168.1.100:11434/api/tags +``` + +##### Setup LM Studio per Rete + +1. Apri LM Studio +2. **Settings** → **Local Server** +3. Configura: + - **Port**: `1234` (o custom) + - **CORS**: ✅ Abilitato (per richieste web) +4. Il server ascolta automaticamente su `0.0.0.0` (tutte le interfacce) + +**Verifica:** +```bash +curl http://192.168.1.50:1234/v1/models +``` + +##### Architetture Comuni + +**Scenario 1: Server AI dedicato** +``` +┌──────────────────────┐ ┌──────────────────────┐ +│ Laptop (DocuMente) │──────▶│ Server GPU │ +│ localhost:8000 │ │ 192.168.1.10:11434 │ +└──────────────────────┘ │ (Ollama/LM Studio) │ + └──────────────────────┘ +``` + +**Scenario 2: Multi-client** +``` + ┌──────────────────────┐ + ┌───────────────▶│ Server AI │ + │ │ 192.168.1.100 │ +┌───┴────┐ │ (Ollama) │ +│ Laptop │ └──────────────────────┘ +│ #1 │◀─────────────────────┐ +└────────┘ │ + │ +┌────────┐ │ +│ Laptop │──────────────────────┘ +│ #2 │ +└────────┘ +``` + +**Scenario 3: VPN Remoto** +``` +┌──────────────────┐ WireGuard ┌──────────────────┐ +│ Laptop (casa) │◀═══════════════▶│ Server (ufficio)│ +│ 10.8.0.2 │ VPN Tunnel │ 10.8.0.1 │ +└──────────────────┘ │ Ollama:11434 │ + └──────────────────┘ +``` + +##### Sicurezza & Firewall + +⚠️ **Attenzione**: Esporre Ollama/LM Studio su IP pubblico può essere rischioso. + +**Firewall (UFW - Ubuntu/Debian):** +```bash +# Permetti solo dalla tua rete locale +sudo ufw allow from 192.168.1.0/24 to any port 11434 + +# O solo IP specifico +sudo ufw allow from 192.168.1.50 to any port 11434 + +# Nega tutto il resto +sudo ufw deny 11434 +``` + +**Firewall (iptables):** +```bash +# Accetta solo da rete locale +sudo iptables -A INPUT -p tcp -s 192.168.1.0/24 --dport 11434 -j ACCEPT +sudo iptables -A INPUT -p tcp --dport 11434 -j DROP +``` + +**SSH Tunnel (alternativa sicura):** +```bash +# Sul client, crea tunnel verso server +ssh -L 11434:localhost:11434 user@192.168.1.100 + +# Poi usa localhost:11434 in DocuMente +OLLAMA_BASE_URL=http://localhost:11434 +``` + +##### Troubleshooting Rete + +**Problema: Connessione rifiutata** +```bash +# Verifica che Ollama ascolti su 0.0.0.0 +sudo netstat -tlnp | grep 11434 +# Deve mostrare: 0.0.0.0:11434, non 127.0.0.1:11434 + +# Verifica firewall +sudo ufw status +sudo iptables -L | grep 11434 +``` + +**Problema: Timeout lunghi** +```bash +# Aumenta timeout in DocuMente (default 120s) +# Per modelli grandi su CPU, può servire più tempo +``` + +**Problema: CORS errors (browser)** +```bash +# LM Studio: assicurati che CORS sia abilitato +# Ollama: usa proxy o disabilita CORS nel browser (solo dev) ``` #### Vantaggi dei Provider Locali