2025-07-22 23:53:10 +08:00
|
|
|
# Base images
|
2025-12-03 14:50:13 +08:00
|
|
|
ARG LITELLM_BUILD_IMAGE=cgr.dev/chainguard/wolfi-base
|
|
|
|
|
ARG LITELLM_RUNTIME_IMAGE=cgr.dev/chainguard/wolfi-base
|
2025-12-16 23:55:53 +08:00
|
|
|
ARG PROXY_EXTRAS_SOURCE=published
|
2024-08-21 06:38:11 +08:00
|
|
|
|
2025-07-22 23:53:10 +08:00
|
|
|
# -----------------
|
|
|
|
|
# Builder Stage
|
|
|
|
|
# -----------------
|
2024-09-21 23:21:11 +08:00
|
|
|
FROM $LITELLM_BUILD_IMAGE AS builder
|
2025-12-16 23:55:53 +08:00
|
|
|
ARG PROXY_EXTRAS_SOURCE
|
2024-08-21 06:38:11 +08:00
|
|
|
WORKDIR /app
|
2025-07-22 23:53:10 +08:00
|
|
|
USER root
|
2025-12-16 23:55:53 +08:00
|
|
|
|
|
|
|
|
# Install build dependencies with retry logic (includes node for UI build)
|
2025-12-07 00:17:50 +08:00
|
|
|
RUN for i in 1 2 3; do \
|
2025-12-16 23:55:53 +08:00
|
|
|
apk add --no-cache \
|
|
|
|
|
python3 \
|
2026-01-23 02:05:09 +08:00
|
|
|
python3-dev \
|
2025-12-16 23:55:53 +08:00
|
|
|
py3-pip \
|
|
|
|
|
clang \
|
|
|
|
|
llvm \
|
|
|
|
|
lld \
|
|
|
|
|
gcc \
|
|
|
|
|
linux-headers \
|
|
|
|
|
build-base \
|
|
|
|
|
bash \
|
|
|
|
|
nodejs \
|
|
|
|
|
npm && break || sleep 5; \
|
|
|
|
|
done \
|
2025-08-08 04:31:10 +08:00
|
|
|
&& pip install --no-cache-dir --upgrade pip build
|
2024-08-21 06:38:11 +08:00
|
|
|
|
2025-12-16 23:55:53 +08:00
|
|
|
# Cache Python dependencies
|
|
|
|
|
COPY requirements.txt .
|
|
|
|
|
RUN pip wheel --no-cache-dir --wheel-dir=/wheels/ -r requirements.txt \
|
|
|
|
|
&& pip wheel --no-cache-dir --wheel-dir=/wheels/ "semantic_router==0.1.11" "aurelio-sdk==0.0.19" "PyJWT==2.9.0"
|
|
|
|
|
|
|
|
|
|
# Copy source after dependency layers
|
2024-08-21 06:38:11 +08:00
|
|
|
COPY . .
|
|
|
|
|
|
2025-12-16 23:55:53 +08:00
|
|
|
# Set non-root flag for build time consistency
|
2025-11-06 10:30:20 +08:00
|
|
|
ENV LITELLM_NON_ROOT=true
|
|
|
|
|
|
2025-12-16 23:55:53 +08:00
|
|
|
# Build Admin UI using the upstream command order while keeping a single RUN layer
|
2025-12-24 03:45:31 +08:00
|
|
|
RUN mkdir -p /var/lib/litellm/ui && \
|
2025-12-16 23:55:53 +08:00
|
|
|
npm install -g npm@latest && npm cache clean --force && \
|
|
|
|
|
cd /app/ui/litellm-dashboard && \
|
|
|
|
|
if [ -f "/app/enterprise/enterprise_ui/enterprise_colors.json" ]; then \
|
|
|
|
|
cp /app/enterprise/enterprise_ui/enterprise_colors.json ./ui_colors.json; \
|
|
|
|
|
fi && \
|
|
|
|
|
npm install --legacy-peer-deps && \
|
|
|
|
|
npm run build && \
|
2025-12-24 03:45:31 +08:00
|
|
|
cp -r /app/ui/litellm-dashboard/out/* /var/lib/litellm/ui/ && \
|
|
|
|
|
mkdir -p /var/lib/litellm/assets && \
|
|
|
|
|
cp /app/litellm/proxy/logo.jpg /var/lib/litellm/assets/logo.jpg && \
|
|
|
|
|
( cd /var/lib/litellm/ui && \
|
2025-12-16 23:55:53 +08:00
|
|
|
for html_file in *.html; do \
|
|
|
|
|
if [ "$html_file" != "index.html" ] && [ -f "$html_file" ]; then \
|
|
|
|
|
folder_name="${html_file%.html}" && \
|
|
|
|
|
mkdir -p "$folder_name" && \
|
|
|
|
|
mv "$html_file" "$folder_name/index.html"; \
|
|
|
|
|
fi; \
|
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-06 22:59:36 +08:00
|
|
|
done && \
|
|
|
|
|
touch .litellm_ui_ready ) && \
|
2025-12-16 23:55:53 +08:00
|
|
|
cd /app/ui/litellm-dashboard && rm -rf ./out
|
|
|
|
|
|
|
|
|
|
# Build litellm wheel and place it in wheels dir (replace any PyPI wheels)
|
|
|
|
|
RUN rm -rf dist/* && python -m build && \
|
|
|
|
|
rm -f /wheels/litellm-*.whl && \
|
|
|
|
|
cp dist/*.whl /wheels/
|
2025-11-25 12:45:56 +08:00
|
|
|
|
2025-12-16 23:55:53 +08:00
|
|
|
# Optionally build local litellm-proxy-extras wheel
|
|
|
|
|
RUN if [ "$PROXY_EXTRAS_SOURCE" = "local" ]; then \
|
|
|
|
|
cd /app/litellm-proxy-extras && rm -rf dist && python -m build && \
|
|
|
|
|
cp dist/*.whl /wheels/; \
|
|
|
|
|
fi
|
2025-11-25 12:45:56 +08:00
|
|
|
|
2025-12-16 23:55:53 +08:00
|
|
|
# Pre-cache Prisma binaries in the builder stage
|
|
|
|
|
ENV PRISMA_BINARY_CACHE_DIR=/app/.cache/prisma-python/binaries \
|
|
|
|
|
PRISMA_CLI_BINARY_TARGETS="debian-openssl-3.0.x" \
|
|
|
|
|
XDG_CACHE_HOME=/app/.cache \
|
|
|
|
|
PATH="/usr/lib/python3.13/site-packages/nodejs/bin:${PATH}"
|
2025-11-25 12:45:56 +08:00
|
|
|
|
2025-12-21 09:08:28 +08:00
|
|
|
RUN pip install --no-cache-dir prisma==0.11.0 nodejs-wheel-binaries==24.12.0 \
|
2025-12-16 23:55:53 +08:00
|
|
|
&& mkdir -p /app/.cache/npm
|
2025-11-25 12:45:56 +08:00
|
|
|
|
2025-12-16 23:55:53 +08:00
|
|
|
RUN NPM_CONFIG_CACHE=/app/.cache/npm \
|
|
|
|
|
python -c "import prisma.cli.prisma as p; p.ensure_cached()"
|
2024-08-21 06:38:11 +08:00
|
|
|
|
2025-12-16 23:55:53 +08:00
|
|
|
RUN prisma generate && \
|
|
|
|
|
prisma --version && \
|
|
|
|
|
prisma migrate diff --from-empty --to-schema-datamodel ./schema.prisma --script > /dev/null 2>&1 || true
|
2024-08-21 06:38:11 +08:00
|
|
|
|
2025-07-22 23:53:10 +08:00
|
|
|
# -----------------
|
|
|
|
|
# Runtime Stage
|
|
|
|
|
# -----------------
|
2024-09-21 23:21:11 +08:00
|
|
|
FROM $LITELLM_RUNTIME_IMAGE AS runtime
|
2025-12-16 23:55:53 +08:00
|
|
|
ARG PROXY_EXTRAS_SOURCE
|
2025-07-22 23:53:10 +08:00
|
|
|
WORKDIR /app
|
2025-07-19 02:17:15 +08:00
|
|
|
USER root
|
2025-12-16 23:55:53 +08:00
|
|
|
|
|
|
|
|
# Install runtime dependencies with retry
|
2025-12-07 00:17:50 +08:00
|
|
|
RUN for i in 1 2 3; do \
|
2025-12-16 23:55:53 +08:00
|
|
|
apk upgrade --no-cache && break || sleep 5; \
|
|
|
|
|
done \
|
2025-12-07 00:17:50 +08:00
|
|
|
&& for i in 1 2 3; do \
|
2025-12-16 23:55:53 +08:00
|
|
|
apk add --no-cache python3 py3-pip bash openssl tzdata nodejs npm supervisor && break || sleep 5; \
|
2026-02-01 03:44:43 +08:00
|
|
|
done \
|
2026-02-08 14:23:01 +08:00
|
|
|
&& npm install -g npm@latest tar@7.5.7 glob@11.1.0 @isaacs/brace-expansion@5.0.1 \
|
|
|
|
|
&& GLOBAL="$(npm root -g)" \
|
|
|
|
|
&& find "$GLOBAL/npm" -type d -name "tar" -path "*/node_modules/tar" | while read d; do \
|
|
|
|
|
rm -rf "$d" && cp -rL "$GLOBAL/tar" "$d"; \
|
|
|
|
|
done \
|
|
|
|
|
&& find "$GLOBAL/npm" -type d -name "glob" -path "*/node_modules/glob" | while read d; do \
|
|
|
|
|
rm -rf "$d" && cp -rL "$GLOBAL/glob" "$d"; \
|
|
|
|
|
done \
|
|
|
|
|
&& find "$GLOBAL/npm" -type d -name "brace-expansion" -path "*/node_modules/@isaacs/brace-expansion" | while read d; do \
|
|
|
|
|
rm -rf "$d" && cp -rL "$GLOBAL/@isaacs/brace-expansion" "$d"; \
|
|
|
|
|
done \
|
|
|
|
|
&& npm cache clean --force
|
2024-08-21 06:38:11 +08:00
|
|
|
|
2025-12-16 23:55:53 +08:00
|
|
|
# Copy artifacts from builder
|
|
|
|
|
COPY --from=builder /app/requirements.txt /app/requirements.txt
|
2025-07-22 23:53:10 +08:00
|
|
|
COPY --from=builder /app/docker/entrypoint.sh /app/docker/prod_entrypoint.sh /app/docker/
|
2025-08-24 21:43:57 +08:00
|
|
|
COPY --from=builder /app/docker/supervisord.conf /etc/supervisord.conf
|
2025-12-16 23:55:53 +08:00
|
|
|
COPY --from=builder /app/schema.prisma /app/
|
2026-01-13 00:12:39 +08:00
|
|
|
# Copy prisma_migration.py for Helm migrations job compatibility
|
|
|
|
|
COPY --from=builder /app/litellm/proxy/prisma_migration.py /app/litellm/proxy/prisma_migration.py
|
2024-08-21 06:38:11 +08:00
|
|
|
COPY --from=builder /wheels/ /wheels/
|
2025-12-24 03:45:31 +08:00
|
|
|
COPY --from=builder /var/lib/litellm/ui /var/lib/litellm/ui
|
|
|
|
|
COPY --from=builder /var/lib/litellm/assets /var/lib/litellm/assets
|
2025-12-16 23:55:53 +08:00
|
|
|
COPY --from=builder /app/.cache /app/.cache
|
|
|
|
|
COPY --from=builder /app/litellm-proxy-extras /app/litellm-proxy-extras
|
|
|
|
|
COPY --from=builder \
|
|
|
|
|
/usr/lib/python3.13/site-packages/nodejs* \
|
|
|
|
|
/usr/lib/python3.13/site-packages/prisma* \
|
|
|
|
|
/usr/lib/python3.13/site-packages/tomlkit* \
|
|
|
|
|
/usr/lib/python3.13/site-packages/nodeenv* \
|
|
|
|
|
/usr/lib/python3.13/site-packages/
|
|
|
|
|
COPY --from=builder /usr/bin/prisma /usr/bin/prisma
|
|
|
|
|
|
|
|
|
|
# Final runtime environment configuration
|
|
|
|
|
ENV PRISMA_BINARY_CACHE_DIR=/app/.cache/prisma-python/binaries \
|
|
|
|
|
PRISMA_CLI_BINARY_TARGETS="debian-openssl-3.0.x" \
|
|
|
|
|
HOME=/app \
|
|
|
|
|
LITELLM_NON_ROOT=true \
|
|
|
|
|
XDG_CACHE_HOME=/app/.cache
|
|
|
|
|
|
|
|
|
|
# Install packages from wheels and optional extras without network
|
|
|
|
|
RUN pip install --no-index --find-links=/wheels/ -r requirements.txt && \
|
|
|
|
|
pip install --no-index --find-links=/wheels/ /wheels/litellm-*-py3-none-any.whl && \
|
|
|
|
|
pip install --no-index --find-links=/wheels/ --no-deps semantic_router==0.1.11 && \
|
|
|
|
|
pip install --no-index --find-links=/wheels/ aurelio-sdk==0.0.19 && \
|
|
|
|
|
if [ "$PROXY_EXTRAS_SOURCE" = "local" ]; then \
|
|
|
|
|
if ls /wheels/litellm_proxy_extras-*.whl >/dev/null 2>&1; then \
|
|
|
|
|
pip install --no-index --find-links=/wheels/ /wheels/litellm_proxy_extras-*.whl; \
|
|
|
|
|
else \
|
|
|
|
|
echo "litellm_proxy_extras wheel not found; skipping local install"; \
|
|
|
|
|
fi; \
|
|
|
|
|
fi
|
|
|
|
|
|
2026-02-08 14:23:01 +08:00
|
|
|
# SECURITY FIX: nodejs-wheel-binaries (pip package used by Prisma) bundles a complete
|
|
|
|
|
# npm with old vulnerable deps at /usr/lib/python3.*/site-packages/nodejs_wheel/.
|
|
|
|
|
# Patch every copy of tar, glob, and brace-expansion inside that tree.
|
|
|
|
|
RUN GLOBAL="$(npm root -g)" && \
|
|
|
|
|
find /usr/lib -path "*/nodejs_wheel/*/node_modules/tar" -type d | while read d; do \
|
|
|
|
|
rm -rf "$d" && cp -rL "$GLOBAL/tar" "$d"; \
|
|
|
|
|
done && \
|
|
|
|
|
find /usr/lib -path "*/nodejs_wheel/*/node_modules/glob" -type d | while read d; do \
|
|
|
|
|
rm -rf "$d" && cp -rL "$GLOBAL/glob" "$d"; \
|
|
|
|
|
done && \
|
|
|
|
|
find /usr/lib -path "*/nodejs_wheel/*/node_modules/@isaacs/brace-expansion" -type d | while read d; do \
|
|
|
|
|
rm -rf "$d" && cp -rL "$GLOBAL/@isaacs/brace-expansion" "$d"; \
|
|
|
|
|
done
|
2026-02-08 03:14:55 +08:00
|
|
|
|
2025-12-16 23:55:53 +08:00
|
|
|
# Permissions, cleanup, and Prisma prep
|
2026-01-08 03:36:57 +08:00
|
|
|
# Convert Windows line endings to Unix for entrypoint scripts
|
|
|
|
|
RUN sed -i 's/\r$//' docker/entrypoint.sh && \
|
|
|
|
|
sed -i 's/\r$//' docker/prod_entrypoint.sh && \
|
|
|
|
|
chmod +x docker/entrypoint.sh docker/prod_entrypoint.sh && \
|
2025-12-24 03:45:31 +08:00
|
|
|
mkdir -p /nonexistent /.npm /var/lib/litellm/assets /var/lib/litellm/ui && \
|
|
|
|
|
chown -R nobody:nogroup /app /var/lib/litellm/ui /var/lib/litellm/assets /nonexistent /.npm && \
|
2025-12-16 23:55:53 +08:00
|
|
|
pip uninstall jwt -y || true && \
|
|
|
|
|
pip uninstall PyJWT -y || true && \
|
|
|
|
|
pip install --no-index --find-links=/wheels/ PyJWT==2.10.1 --no-cache-dir && \
|
|
|
|
|
rm -rf /wheels && \
|
|
|
|
|
PRISMA_PATH=$(python -c "import os, prisma; print(os.path.dirname(prisma.__file__))") && \
|
|
|
|
|
chown -R nobody:nogroup $PRISMA_PATH && \
|
|
|
|
|
LITELLM_PKG_MIGRATIONS_PATH="$(python -c 'import os, litellm_proxy_extras; print(os.path.dirname(litellm_proxy_extras.__file__))' 2>/dev/null || echo '')/migrations" && \
|
|
|
|
|
[ -n "$LITELLM_PKG_MIGRATIONS_PATH" ] && chown -R nobody:nogroup $LITELLM_PKG_MIGRATIONS_PATH && \
|
|
|
|
|
LITELLM_PROXY_EXTRAS_PATH=$(python -c "import os, litellm_proxy_extras; print(os.path.dirname(litellm_proxy_extras.__file__))" 2>/dev/null || echo "") && \
|
2025-12-24 03:45:31 +08:00
|
|
|
chgrp -R 0 $PRISMA_PATH /var/lib/litellm/ui /var/lib/litellm/assets && \
|
2025-12-16 23:55:53 +08:00
|
|
|
[ -n "$LITELLM_PROXY_EXTRAS_PATH" ] && chgrp -R 0 $LITELLM_PROXY_EXTRAS_PATH || true && \
|
2025-12-24 03:45:31 +08:00
|
|
|
chmod -R g=u $PRISMA_PATH /var/lib/litellm/ui /var/lib/litellm/assets && \
|
2025-12-16 23:55:53 +08:00
|
|
|
[ -n "$LITELLM_PROXY_EXTRAS_PATH" ] && chmod -R g=u $LITELLM_PROXY_EXTRAS_PATH || true && \
|
2025-12-24 03:45:31 +08:00
|
|
|
chmod -R g+w $PRISMA_PATH /var/lib/litellm/ui /var/lib/litellm/assets && \
|
2025-12-16 23:55:53 +08:00
|
|
|
[ -n "$LITELLM_PROXY_EXTRAS_PATH" ] && chmod -R g+w $LITELLM_PROXY_EXTRAS_PATH || true && \
|
|
|
|
|
chmod -R g+rX $PRISMA_PATH && \
|
|
|
|
|
chmod -R g+rX /app/.cache && \
|
2026-01-30 11:04:59 +08:00
|
|
|
mkdir -p /tmp/.npm /nonexistent /.npm
|
2025-12-16 23:55:53 +08:00
|
|
|
|
|
|
|
|
# Switch to non-root user for runtime
|
2025-01-16 13:49:03 +08:00
|
|
|
USER nobody
|
|
|
|
|
|
2026-01-30 11:04:59 +08:00
|
|
|
# Generate Prisma client as nobody user to ensure correct file ownership
|
|
|
|
|
RUN prisma generate
|
|
|
|
|
|
2025-12-16 23:55:53 +08:00
|
|
|
# Prisma runtime knobs for offline containers
|
|
|
|
|
ENV PRISMA_SKIP_POSTINSTALL_GENERATE=1 \
|
|
|
|
|
PRISMA_HIDE_UPDATE_MESSAGE=1 \
|
|
|
|
|
PRISMA_ENGINES_CHECKSUM_IGNORE_MISSING=1 \
|
|
|
|
|
NPM_CONFIG_CACHE=/app/.cache/npm \
|
|
|
|
|
NPM_CONFIG_PREFER_OFFLINE=true \
|
|
|
|
|
PRISMA_OFFLINE_MODE=true
|
2025-01-16 13:49:03 +08:00
|
|
|
|
2024-08-21 06:38:11 +08:00
|
|
|
EXPOSE 4000/tcp
|
2025-07-22 23:53:10 +08:00
|
|
|
ENTRYPOINT ["/app/docker/prod_entrypoint.sh"]
|
2025-12-16 23:55:53 +08:00
|
|
|
CMD ["--port", "4000"]
|