stuxf
7066c895f6
* chore: harden npm supply chain — pin overrides, enforce npm ci, add ignore-scripts Replace open-ended >= version overrides with exact pins matching lockfile versions across all 6 package.json files. Remove dead overrides for packages not present in lockfiles. Switch CI and devcontainer from npm install to npm ci for deterministic lockfile-based installs. Add .npmrc to all 7 JS project directories with ignore-scripts=true (blocks postinstall RAT vectors like the axios@1.14.1 supply chain attack) and min-release-age=3d (refuses packages published <3 days ago, requires npm >=11.10). Remove Yarn-only resolutions field from docs/my-website. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * chore: bump sharp to 0.33.5 in docs, add docs .npmrc sharp 0.32.x uses postinstall to download native binaries, which breaks with ignore-scripts=true. sharp 0.33+ distributes via optionalDependencies instead, making it compatible with the new .npmrc hardening. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * chore: remove docs .npmrc to fix Vercel deploy Vercel's build for docs/my-website uses npm install which needs sharp 0.32.6's postinstall script. Since we don't control Vercel's build process, remove the .npmrc from docs rather than fight it. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * chore: Dockerfile npm ci + nvm checksum verification - Replace npm install with npm ci in Dockerfile.non_root, Dockerfile.custom_ui, and spend-logs/Dockerfile for deterministic lockfile-based installs - Replace curl-pipe-bash nvm install with download-then-verify pattern in build_admin_ui.sh, build_ui.sh, and build_ui_custom_path.sh - Update nvm from v0.38.0 (2021) to v0.40.4 (Jan 2026) with SHA256 checksum verification before execution Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: macOS sha256sum compat + clarify min-release-age scope - Use shasum -a 256 fallback on macOS where sha256sum is unavailable - Clarify in .npmrc comments that min-release-age only protects local npm install, not npm ci (used in CI) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Docker Development Guide
This guide provides instructions for building and running the LiteLLM application using Docker and Docker Compose.
Prerequisites
- Docker
- Docker Compose
Building and Running the Application
To build and run the application, you will use the docker-compose.yml file located in the root of the project. This file is configured to use the Dockerfile.non_root for a secure, non-root container environment.
1. Set the Master Key
The application requires a MASTER_KEY for signing and validating tokens. You must set this key as an environment variable before running the application.
Create a .env file in the root of the project and add the following line:
MASTER_KEY=your-secret-key
Replace your-secret-key with a strong, randomly generated secret.
2. Build and Run the Containers
Once you have set the MASTER_KEY, you can build and run the containers using the following command:
docker compose up -d --build
This command will:
- Build the Docker image using
Dockerfile.non_root. - Start the
litellm,litellm_db, andprometheusservices in detached mode (-d). - The
--buildflag ensures that the image is rebuilt if there are any changes to the Dockerfile or the application code.
3. Verifying the Application is Running
You can check the status of the running containers with the following command:
docker compose ps
To view the logs of the litellm container, run:
docker compose logs -f litellm
4. Stopping the Application
To stop the running containers, use the following command:
docker compose down
Hardened / Offline Testing
To ensure changes are safe for non-root, read-only root filesystems and restricted egress, always validate with the hardened compose file:
docker compose -f docker-compose.yml -f docker-compose.hardened.yml build --no-cache
docker compose -f docker-compose.yml -f docker-compose.hardened.yml up -d
This setup:
- Builds from
docker/Dockerfile.non_rootwith Prisma engines and Node toolchain baked into the image. - Runs the proxy as a non-root user with a read-only rootfs and only writable tmpfs mounts:
/app/cache(Prisma/NPM cache; backingPRISMA_BINARY_CACHE_DIR,NPM_CONFIG_CACHE,XDG_CACHE_HOME)/app/migrations(Prisma migration workspace; backingLITELLM_MIGRATION_DIR)
- Pre-builds and serves the admin UI from read-only paths:
/var/lib/litellm/ui(pre-restructured Next.js UI with.litellm_ui_readymarker)/var/lib/litellm/assets(UI logos and assets)
- Routes all outbound traffic through a local Squid proxy that denies egress, so Prisma migrations must use the cached CLI and engines.
You should also verify offline Prisma behaviour with:
docker run --rm --network none --entrypoint prisma ghcr.io/berriai/litellm:main-stable --version
This command should succeed (showing engine versions) even with --network none, confirming that Prisma binaries are available without network access.
Troubleshooting
build_admin_ui.sh: not found: This error can occur if the Docker build context is not set correctly. Ensure that you are running thedocker-composecommand from the root of the project.Master key is not initialized: This error means theMASTER_keyenvironment variable is not set. Make sure you have created a.envfile in the project root with theMASTER_KEYdefined.