diff --git a/.env.example b/.env.example index ef1d647..6f1d1da 100644 --- a/.env.example +++ b/.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= diff --git a/docs/features/ollama.md b/docs/features/ollama.md index 1f9c4c1..3b4d490 100644 --- a/docs/features/ollama.md +++ b/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:** diff --git a/docs/features/openai-compatible.md b/docs/features/openai-compatible.md index c463350..460dd8c 100644 --- a/docs/features/openai-compatible.md +++ b/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 diff --git a/docs/troubleshooting/common-issues.md b/docs/troubleshooting/common-issues.md index c6b4ae9..aaef124 100644 --- a/docs/troubleshooting/common-issues.md +++ b/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.).