Merge pull request #107 from thushan/fix/proxy-path

fix: Proxy Path issue & sensible defaults

Author: thushan

docs/content/concepts/health-checking.md

@@ -10,15 +10,17 @@ keywords: ["health checking", "endpoint monitoring", "circuit breaker", "olla he
 > ```yaml
 > endpoints:
 >   - url: "http://localhost:11434"
->     check_interval: 30s
->     check_timeout: 5s
+>     check_interval: 5s
+>     check_timeout: 2s
 > ```
 > **Supported Settings**:
 > 
-> - `check_interval` _(default: 30s)_ - Time between health checks
-> - `check_timeout` _(default: 5s)_ - Maximum time to wait for response
+> - `check_interval` _(default: 5s)_ - Time between health checks
+> - `check_timeout` _(default: 2s)_ - Maximum time to wait for response
 > - `check_path` _(auto-detected)_ - Health check endpoint path
 > 
+> **Note**: Both `check_interval` and `check_timeout` are optional with sensible defaults (5s and 2s respectively), so you don't need to specify them for basic setups.
+>
 > **Environment Variables**: Per-endpoint settings not supported via env vars
 
 Olla continuously monitors the health of all configured endpoints to ensure requests are only routed to available backends. The health checking system is automatic and requires minimal configuration.

docs/content/concepts/model-unification.md

@@ -12,13 +12,13 @@ keywords: model unification, model catalogue, ollama models, lm studio models, m
 >   model_discovery:
 >     enabled: true
 >     interval: 5m
->     concurrent_workers: 3
+>     concurrent_workers: 5
 > ```
 > **Supported Settings**:
 > 
 > - `enabled` _(default: true)_ - Enable automatic model discovery
 > - `interval` _(default: 5m)_ - How often to refresh model lists
-> - `concurrent_workers` _(default: 3)_ - Parallel discovery workers
+> - `concurrent_workers` _(default: 5)_ - Parallel discovery workers
 > 
 > **Environment Variables**: 
 > - `OLLA_DISCOVERY_MODEL_DISCOVERY_ENABLED`

docs/content/configuration/overview.md

@@ -232,14 +232,14 @@ discovery:
 
 ### Endpoint Configuration
 
-Each endpoint requires:
+Each endpoint requires `url`, `name`, and `type`. The `priority` field is optional:
 
 | Field | Description | Example |
 |-------|-------------|---------|
 | **url** | Base URL of the endpoint | `http://localhost:11434` |
 | **name** | Unique identifier | `local-ollama` |
 | **type** | Platform type | `llamacpp`, `vllm`, `openai` (See [integrations](../integrations/overview.md#backend-endpoints)) |
-| **priority** | Selection priority (higher = preferred) | `100` |
+| **priority** | Selection priority (higher = preferred, default: `100`) | `100` |
 
 Current list of supported types can be found in [integrations](../integrations/overview.md#backend-endpoints).
 

docs/content/configuration/practices/performance.md

@@ -128,18 +128,18 @@ proxy:
 
 ### Health Check Optimisation
 
-Balance detection speed vs overhead:
+Balance detection speed vs overhead (the default `check_interval` is `5s`):
 
 ```yaml
 endpoints:
   - url: "http://localhost:11434"
-    check_interval: 30s    # Not too frequent
+    check_interval: 30s    # Increase from 5s default to reduce overhead
     check_timeout: 2s      # Fast failure detection
 ```
 
 Too frequent checks waste resources:
 
-- 5s interval = 12 checks/minute/endpoint
+- 5s interval (default) = 12 checks/minute/endpoint
 - 30s interval = 2 checks/minute/endpoint
 - With 10 endpoints, that's 120 vs 20 checks/minute
 
@@ -162,7 +162,7 @@ Typical memory usage:
 # Memory-conscious configuration
 server:
   request_limits:
-    max_body_size: 5242880    # 5MB instead of 50MB
+    max_body_size: 5242880    # 5MB instead of default 100MB
     max_header_size: 65536    # 64KB instead of 512KB
 
 model_registry:

docs/content/configuration/reference.md

@@ -237,12 +237,12 @@ discovery:
 | `static.endpoints[].url` | string | Yes | Endpoint base URL |
 | `static.endpoints[].name` | string | Yes | Unique endpoint name |
 | `static.endpoints[].type` | string | Yes | Backend type (`ollama`, `lm-studio`, `llamacpp`, `vllm`, `sglang`, `lemonade`, `litellm`, `openai`) |
-| `static.endpoints[].priority` | int | No | Selection priority (higher=preferred) |
+| `static.endpoints[].priority` | int | No | Selection priority (higher=preferred, default: `100`) |
 | `static.endpoints[].preserve_path` | bool | No | Preserve base path in URL when proxying (default: `false`) |
 | `static.endpoints[].health_check_url` | string | No | Health check path (optional, uses profile default if not specified) |
 | `static.endpoints[].model_url` | string | No | Model discovery path (optional, uses profile default if not specified) |
-| `static.endpoints[].check_interval` | duration | No | Health check interval |
-| `static.endpoints[].check_timeout` | duration | No | Health check timeout |
+| `static.endpoints[].check_interval` | duration | No | Health check interval (default: `5s`) |
+| `static.endpoints[].check_timeout` | duration | No | Health check timeout (default: `2s`) |
 | `static.endpoints[].model_filter` | object | No | Model filtering for this endpoint |
 
 #### URL Configuration
@@ -377,7 +377,7 @@ discovery:
 | `model_discovery.timeout` | duration | `30s` | Discovery timeout |
 | `model_discovery.concurrent_workers` | int | `5` | Parallel workers |
 | `model_discovery.retry_attempts` | int | `3` | Retry attempts |
-| `model_discovery.retry_backoff` | duration | `5s` | Retry backoff |
+| `model_discovery.retry_backoff` | duration | `1s` | Retry backoff |
 
 Example:
 
@@ -389,7 +389,7 @@ discovery:
     timeout: 30s
     concurrent_workers: 10
     retry_attempts: 3
-    retry_backoff: 5s
+    retry_backoff: 1s
 ```
 
 ## Model Registry Configuration
@@ -455,7 +455,7 @@ model_registry:
 |-------|------|---------|-------------|
 | `unification.enabled` | bool | `true` | Enable unification |
 | `unification.stale_threshold` | duration | `24h` | Model retention time |
-| `unification.cleanup_interval` | duration | `10m` | Cleanup frequency |
+| `unification.cleanup_interval` | duration | `5m` | Cleanup frequency |
 | `unification.cache_ttl` | duration | `10m` | Cache TTL |
 
 Example:
@@ -764,7 +764,7 @@ discovery:
     timeout: 30s
     concurrent_workers: 5
     retry_attempts: 3
-    retry_backoff: 5s
+    retry_backoff: 1s
   static:
     endpoints: []
 
@@ -780,7 +780,7 @@ model_registry:
   unification:
     enabled: true
     stale_threshold: 24h
-    cleanup_interval: 10m
+    cleanup_interval: 5m
     cache_ttl: 10m
     custom_rules: []
 
@@ -814,6 +814,14 @@ Olla validates configuration on startup:
 - Ports must be in valid range (1-65535)
 - CIDR blocks must be valid
 
+Additionally, Olla's `Validate()` method catches dangerous zero or empty configuration values that would cause panics or silent failures at runtime. It runs after all config sources (file, environment overrides) have been merged, so the final state is what gets checked. The following conditions produce clear error messages at startup:
+
+- `proxy.engine` is empty
+- `proxy.load_balancer` is empty
+- `discovery.type` is empty
+- `server.port` is zero or negative
+- When `model_discovery.enabled` is `true`: `interval`, `concurrent_workers`, or `timeout` is zero
+
 ## Next Steps
 
 - [Configuration Examples](examples.md) - Common configurations

docs/content/faq.md

@@ -117,18 +117,18 @@ proxy:
 
 server:
   request_limits:
-    max_body_size: 5242880  # 5MB instead of default 50MB
+    max_body_size: 5242880  # 5MB instead of default 100MB
 ```
 
 ### Models not appearing
 
-If models aren't being discovered:
+Model discovery is enabled by default. If models aren't being discovered:
 
-1. Check model discovery is enabled:
+1. Verify it hasn't been explicitly disabled in your configuration:
    ```yaml
    discovery:
      model_discovery:
-       enabled: true
+       enabled: false  # Remove this line or set to true
    ```
 
 2. Verify endpoints are healthy:

docs/content/getting-started/quickstart.md

@@ -58,13 +58,14 @@ discovery:
         name: "local-ollama"
         type: "ollama"
         priority: 100
-        health_check_url: "/"
 
 logging:
   level: "info"
   format: "json"
 ```
 
+Settings like `check_interval`, `check_timeout`, and `priority` are optional -- Olla provides sensible defaults for each backend type via its profile system.
+
 The rest will be from the shipped defaults.
 
 ### 2. Start Olla

docs/content/integrations/backend/ollama.md

@@ -88,10 +88,10 @@ discovery:
         name: "local-ollama"
         type: "ollama"
         priority: 100
-        model_url: "/api/tags"
-        health_check_url: "/"
-        check_interval: 2s
-        check_timeout: 1s
+        model_url: "/api/tags"        # optional, profile default: /api/tags
+        health_check_url: "/"          # optional, profile default: /
+        check_interval: 2s             # optional, default: 5s
+        check_timeout: 1s              # optional, default: 2s
 ```
 
 ### Multiple Ollama Instances