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.
2026-04-06 18:31:57 +02:00
parent 0b33cd1619
commit fbbd3ed50c
1 changed files with 167 additions and 3 deletions
--- 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