Merge pull request #281 from lfnovo/fix/ssl

docs: add SSL verification configuration for local providers

.env.example

@@ -73,6 +73,19 @@ API_URL=http://localhost:5055
 #
 # ESPERANTO_LLM_TIMEOUT=60
 
+# SSL VERIFICATION CONFIGURATION
+# Configure SSL certificate verification for local AI providers (Ollama, LM Studio, etc.)
+# behind reverse proxies with self-signed certificates
+#
+# Option 1: Custom CA Bundle (recommended for self-signed certs)
+# Point to your CA certificate file to verify SSL while using custom certificates
+# ESPERANTO_SSL_CA_BUNDLE=/path/to/your/ca-bundle.pem
+#
+# Option 2: Disable SSL Verification (development only)
+# WARNING: Disabling SSL verification exposes you to man-in-the-middle attacks
+# Only use in trusted development/testing environments
+# ESPERANTO_SSL_VERIFY=false
+
 # SECURITY
 # Set this to protect your Open Notebook instance with a password (for public hosting)
 # OPEN_NOTEBOOK_PASSWORD=

docs/features/ollama.md

@@ -431,6 +431,45 @@ export OLLAMA_FLASH_ATTENTION=1        # Enable flash attention (if supported)
 export OLLAMA_API_BASE=http://localhost:11434
 ```
 
+### SSL Configuration (Self-Signed Certificates)
+
+If you're running Ollama behind a reverse proxy with self-signed SSL certificates (e.g., Caddy, nginx with custom certs), you may encounter SSL verification errors:
+
+```
+[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate
+```
+
+**Solutions:**
+
+**Option 1: Use a custom CA bundle (recommended)**
+```bash
+# Point to your CA certificate file
+export ESPERANTO_SSL_CA_BUNDLE=/path/to/your/ca-bundle.pem
+```
+
+**Option 2: Disable SSL verification (development only)**
+```bash
+# WARNING: Only use in trusted development environments
+export ESPERANTO_SSL_VERIFY=false
+```
+
+**Docker Compose example with SSL configuration:**
+```yaml
+services:
+  open-notebook:
+    image: lfnovo/open_notebook:v1-latest-single
+    environment:
+      - OLLAMA_API_BASE=https://ollama.local:11434
+      # Option 1: Custom CA bundle
+      - ESPERANTO_SSL_CA_BUNDLE=/certs/ca-bundle.pem
+      # Option 2: Disable verification (dev only)
+      # - ESPERANTO_SSL_VERIFY=false
+    volumes:
+      - /path/to/your/ca-bundle.pem:/certs/ca-bundle.pem:ro
+```
+
+> **Security Note:** Disabling SSL verification exposes you to man-in-the-middle attacks. Always prefer using a custom CA bundle in production environments.
+
 ### Custom Model Imports
 
 **Import custom models:**

docs/features/openai-compatible.md

@@ -339,11 +339,51 @@ export OPENAI_COMPATIBLE_BASE_URL=http://192.168.1.100:1234/v1
 ```
 
 **Security Notes:**
-- ⚠️ Only use on trusted networks
+- Only use on trusted networks
 - Consider using HTTPS for production
 - Implement API key authentication if possible
 - Use firewall rules to restrict access
 
+### SSL Configuration (Self-Signed Certificates)
+
+If you're running your OpenAI-compatible service behind a reverse proxy with self-signed SSL certificates (e.g., Caddy, nginx with custom certs), you may encounter SSL verification errors:
+
+```
+[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate
+Connection error.
+```
+
+**Solutions:**
+
+**Option 1: Use a custom CA bundle (recommended)**
+```bash
+# Point to your CA certificate file
+export ESPERANTO_SSL_CA_BUNDLE=/path/to/your/ca-bundle.pem
+```
+
+**Option 2: Disable SSL verification (development only)**
+```bash
+# WARNING: Only use in trusted development environments
+export ESPERANTO_SSL_VERIFY=false
+```
+
+**Docker Compose example with SSL configuration:**
+```yaml
+services:
+  open-notebook:
+    image: lfnovo/open_notebook:v1-latest-single
+    environment:
+      - OPENAI_COMPATIBLE_BASE_URL=https://lmstudio.local:1234/v1
+      # Option 1: Custom CA bundle
+      - ESPERANTO_SSL_CA_BUNDLE=/certs/ca-bundle.pem
+      # Option 2: Disable verification (dev only)
+      # - ESPERANTO_SSL_VERIFY=false
+    volumes:
+      - /path/to/your/ca-bundle.pem:/certs/ca-bundle.pem:ro
+```
+
+> **Security Note:** Disabling SSL verification exposes you to man-in-the-middle attacks. Always prefer using a custom CA bundle in production environments.
+
 ### Port Conflicts
 
 **Problem**: Default port (1234) is already in use

docs/troubleshooting/common-issues.md

@@ -286,6 +286,53 @@ Or provide it when logging into the web interface.
 
 ## Runtime Errors
 
+### SSL Certificate Verification Errors
+
+**Problem**: SSL verification errors when connecting to local AI providers (Ollama, LM Studio) behind reverse proxies with self-signed certificates.
+
+**Symptoms**:
+- `[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate`
+- `Connection error` when using HTTPS endpoints
+- Works with HTTP but fails with HTTPS
+
+**Cause**: Python's SSL verification uses the `certifi` package certificate store, not the system's certificate store. Self-signed certificates are not trusted by default.
+
+**Solutions**:
+
+1. **Use a custom CA bundle (recommended)**:
+   ```bash
+   # Add to your .env or docker-compose.yml
+   ESPERANTO_SSL_CA_BUNDLE=/path/to/your/ca-bundle.pem
+   ```
+
+   For Docker, mount the certificate:
+   ```yaml
+   services:
+     open-notebook:
+       environment:
+         - ESPERANTO_SSL_CA_BUNDLE=/certs/ca-bundle.pem
+       volumes:
+         - /path/to/your/ca-bundle.pem:/certs/ca-bundle.pem:ro
+   ```
+
+2. **Disable SSL verification (development only)**:
+   ```bash
+   # WARNING: Only use in trusted development environments
+   ESPERANTO_SSL_VERIFY=false
+   ```
+
+3. **Use HTTP instead of HTTPS**:
+   - If your services are on a trusted local network, using HTTP is acceptable
+   - Change your endpoint URL from `https://` to `http://`
+
+> **Security Note:** Disabling SSL verification exposes you to man-in-the-middle attacks. Always prefer using a custom CA bundle or HTTP on trusted networks.
+
+**Related Documentation:**
+- [Ollama SSL Configuration](../features/ollama.md#ssl-configuration-self-signed-certificates)
+- [OpenAI-Compatible SSL Configuration](../features/openai-compatible.md#ssl-configuration-self-signed-certificates)
+
+---
+
 ### AI Provider API Errors
 
 **Problem**: Errors when using AI models (OpenAI, Anthropic, etc.).