mirror of
https://github.com/BerriAI/litellm.git
synced 2026-08-28 05:25:59 +00:00
487074f602
* chore(build): move the Admin UI toolchain to Node 24 Node 18 and Node 20 both reached end of life (2025-04-30 and 2026-04-30), and the release images along with every CI lane were still building on them. Node 24 is the current LTS through 2028-04-30, so this moves the four UI build images, the CircleCI lanes, and the four GitHub Actions workflows onto it Node 24 also ships npm 11.17, which is the first line that implements the min-release-age setting this repo already carries in its .npmrc files. On npm 10 the key is parsed and discarded, so the release-age gate has had no effect regardless of its value. Tightening the dashboard's engines range and turning on engine-strict makes an unsupported npm fail loudly rather than skip the gate quietly, and a new step in the UI build workflow probes an impossible cooldown so an inert setting cannot pass unnoticed again Node 24's bundled undici tightened its brand check on RequestInit.signal, which rejects the AbortSignal jsdom installs and broke the two cases in src/lib/http/api.test.ts that rebase a request onto a runtime base url. Under jsdom the Request global comes from Node while AbortSignal comes from jsdom; tests/jsdomFetchEnv.ts delegates to the jsdom environment and then restores Node's native AbortController and AbortSignal so both come from one realm. Upgrading jsdom does not address this, as jsdom still does not own Request The workflows now read ui/litellm-dashboard/.nvmrc instead of repeating a literal, so the Node version has a single source of truth, and ui/Dockerfile is pinned by digest to match the other three build images. The lockfile changes are npm 11 normalising the engines range and dropping optional peer entries it no longer records * fix(build): point every Admin UI build script at .nvmrc The enterprise Docker path was left on Node 18. docker/build_admin_ui.sh runs only when enterprise/enterprise_ui/enterprise_colors.json is present, which it never is in the OSS tree, so neither CI nor a default image build reaches it; it pinned nvm to v18.17.0 and then built the dashboard, which now requires Node 24, so a customized enterprise image would have failed EBADENGINE All three UI build scripts now resolve the version from ui/litellm-dashboard/.nvmrc rather than carrying their own pin, so the Node version has a single home across Docker, CI, and local builds. build_ui.sh was on v20 and build_ui_custom_path.sh on v18.17.0 Also drops the dependency-cooldown probe from the UI build workflow. The engines floor plus engine-strict already fails an unsupported npm loudly at install time, so the probe was redundant, and treating any nonzero exit from a live registry call as proof of enforcement made it unsound besides |
||
|---|---|---|
| .. | ||
| build_from_pip | ||
| tests | ||
| .env.example | ||
| build_admin_ui.sh | ||
| component_entrypoint.sh | ||
| Dockerfile.database | ||
| Dockerfile.non_root | ||
| entrypoint.sh | ||
| install_auto_router.sh | ||
| prod_entrypoint.sh | ||
| README.md | ||
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 LITELLM_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:
LITELLM_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 LITELLM_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 theLITELLM_MASTER_KEYenvironment variable is not set. Make sure you have created a.envfile in the project root with theLITELLM_MASTER_KEYdefined.