cb95b1cf92
fix: Add LITELLM_UI_PATH and LITELLM_ASSETS_PATH for read-only filesystem support ( #20492 )
...
Fixes #19578
---
When deploying the LiteLLM proxy with `readOnlyRootFilesystem: true` in Kubernetes, UI routes returned `404` because:
- Hardcoded paths:
- `/var/lib/litellm/ui`
- `/var/lib/litellm/assets`
- Runtime copy/restructure operations failed on read-only filesystems
- No detection mechanism for pre-restructured UI
---
Add configurable environment variables with intelligent detection, graceful fallbacks, and code quality improvements.
---
- **`LITELLM_UI_PATH`** — Custom UI directory location
- Default: `/var/lib/litellm/ui` (when `LITELLM_NON_ROOT=true`)
- Default: packaged UI path (otherwise)
- Example: `/app/var/litellm/ui` for `emptyDir` volumes
- **`LITELLM_ASSETS_PATH`** — Custom assets directory location
- Default: `/var/lib/litellm/assets` (when `LITELLM_NON_ROOT=true`)
- Default: current working directory (otherwise)
- Example: `/app/var/litellm/assets`
---
UI is detected as **pre-restructured and ready** if any of the following apply:
1. **Primary**: `.litellm_ui_ready` marker file exists (created by Dockerfile)
2. **Fallback**: Pattern-based detection — finds *any* subdirectory containing `index.html`
(resilient to UI structure changes; no hardcoded route names)
3. **Safety**: Filesystem writability check before operations
---
**`litellm/proxy/proxy_server.py`**
- `_validate_ui_directory()` — Verifies UI has required structure (`index.html`, `_next/`)
- `_is_ui_pre_restructured()` — Pattern-based detection (not hardcoded routes)
- `_try_populate_ui_directory()` — Helper for clean error handling
- Refactored UI path decision tree with numbered cases (1, 2, 3, 4a, 4b)
- Updated UI path logic to use `LITELLM_UI_PATH`
- Added writability checks before copy/restructure operations
- Graceful fallback to packaged UI if operations fail
- Updated `server_root_path` replacement with read-only check
- Simplified assets directory creation (try/except instead of complex parent checks)
- Updated `get_image()` endpoint to use `LITELLM_ASSETS_PATH`
- Added validation for packaged and final UI paths
**`docker/Dockerfile.non_root`**
- Added `touch .litellm_ui_ready` marker after UI restructuring
- Enables automatic detection of pre-built UI in Docker images
**`tests/proxy_unit_tests/test_ui_path_detection.py`**
- Added comprehensive unit tests for new functionality
- Tests env var handling, detection logic, and writability checks
---
**`docs/my-website/docs/proxy/config_settings.md`**
- Added `LITELLM_UI_PATH` and `LITELLM_ASSETS_PATH` to env vars table
- Documented defaults and use cases
**`docs/my-website/docs/proxy/prod.md`**
- Added comprehensive "Read-Only Root Filesystem" section
- Quick fixes for permission errors
- Full Kubernetes setup with `initContainer` + `emptyDir` volumes
- API-only deployment option
- Environment variables reference table
- Notes on migrations, caching, and `server_root_path`
**`docker/README.md`**
- Updated hardened setup notes to mention pre-built UI
- Added details about UI serving from read-only paths
---
- No breaking changes
- Existing deployments continue working without modifications
- New env vars are optional with sensible defaults
- Detection logic supports both old and new builds
- Graceful fallbacks throughout
---
```yaml
apiVersion: apps/v1
kind: Deployment
spec:
template:
spec:
initContainers:
- name: setup-ui
image: ghcr.io/berriai/litellm:main-stable
command: ["sh", "-c", "cp -r /var/lib/litellm/ui/* /app/var/litellm/ui/"]
volumeMounts:
- name: ui-volume
mountPath: /app/var/litellm/ui
containers:
- name: litellm
env:
- name: LITELLM_UI_PATH
value: "/app/var/litellm/ui"
- name: LITELLM_ASSETS_PATH
value: "/app/var/litellm/assets"
securityContext:
readOnlyRootFilesystem: true
volumeMounts:
- name: ui-volume
mountPath: /app/var/litellm/ui
volumes:
- name: ui-volume
emptyDir:
sizeLimit: 100Mi
2026-02-12 19:39:04 +05:30
Achilleas Athanasiou Fragkoulis