From 7590012a03998278cc66fc14bf7506f44124e68c Mon Sep 17 00:00:00 2001 From: Yuneng Jiang Date: Mon, 21 Sep 2026 14:12:55 -0700 Subject: [PATCH 1/2] feat(docker): add a quickstart compose file served from the product repo The docs quickstart pipes a compose file hosted on the docs site straight into `docker compose -f -`. That puts the content users execute in the docs repo rather than here, and nothing lands on disk for them to read first. Move the two-service stack (gateway + Postgres) into docker/ so it ships and is reviewed alongside the code it starts, and pin the image to main-stable instead of latest. The docs change to download-then-run follows separately. Verified: `docker compose up -d` brings the stack healthy, /health/liveliness returns 200, /v1/models returns 200 with the placeholder key and 401 without, and /ui/ serves. --- docker/README.md | 10 +++++++ docker/docker-compose.quickstart.yml | 40 ++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+) create mode 100644 docker/docker-compose.quickstart.yml diff --git a/docker/README.md b/docker/README.md index 26d8c9a37b0..787866ce35a 100644 --- a/docker/README.md +++ b/docker/README.md @@ -2,6 +2,16 @@ This guide provides instructions for building and running the LiteLLM application using Docker and Docker Compose. +> **Just want to run LiteLLM?** This guide builds from source. To run the published +> image instead, use `docker-compose.quickstart.yml` in this directory — the +> two-service stack (gateway + Postgres) that the +> [Docker quickstart](https://docs.litellm.ai/docs/proxy/docker_quick_start) documents: +> +> ```bash +> curl -sSLO https://github.com/BerriAI/litellm/raw/main/docker/docker-compose.quickstart.yml +> docker compose -f docker-compose.quickstart.yml up -d +> ``` + ## Prerequisites - Docker diff --git a/docker/docker-compose.quickstart.yml b/docker/docker-compose.quickstart.yml new file mode 100644 index 00000000000..7c849c759f0 --- /dev/null +++ b/docker/docker-compose.quickstart.yml @@ -0,0 +1,40 @@ +# LiteLLM quickstart stack: the gateway plus a Postgres database that stores +# models, virtual keys, and spend logs. Used by +# https://docs.litellm.ai/docs/proxy/docker_quick_start +# +# curl -sSLO https://github.com/BerriAI/litellm/raw/main/docker/docker-compose.quickstart.yml +# docker compose -f docker-compose.quickstart.yml up -d +# +# The credentials below are placeholders for local evaluation. Before any real +# use, set LITELLM_MASTER_KEY and LITELLM_SALT_KEY to long random values and +# pin the image to a specific release tag. +services: + litellm: + image: docker.litellm.ai/berriai/litellm:main-stable + ports: + - "4000:4000" + environment: + LITELLM_MASTER_KEY: sk-1234 + LITELLM_SALT_KEY: sk-XXXXXXXXXXXXXXXX + DATABASE_URL: postgresql://litellm:litellm@db:5432/litellm + STORE_MODEL_IN_DB: "True" + depends_on: + db: + condition: service_healthy + + db: + image: postgres:16 + environment: + POSTGRES_USER: litellm + POSTGRES_PASSWORD: litellm + POSTGRES_DB: litellm + healthcheck: + test: ["CMD-SHELL", "pg_isready -U litellm"] + interval: 5s + timeout: 5s + retries: 10 + volumes: + - postgres_data:/var/lib/postgresql/data + +volumes: + postgres_data: From d1b160310f680f6c19e63dd8cd492847c66ce684 Mon Sep 17 00:00:00 2001 From: Yuneng Jiang Date: Mon, 21 Sep 2026 14:27:29 -0700 Subject: [PATCH 2/2] fix(docker): require a generated master key in the quickstart stack The committed sk-1234 placeholder is in PUBLICLY_KNOWN_MASTER_KEYS, so once an image ships fe480533e8 the proxy refuses to boot and the quickstart stops working. It also meant the documented stack came up on port 4000 with a credential anyone could guess. Both keys now come from .env and compose refuses to render without them. The salt key is generated alongside so it stays stable across restarts, which keeps stored credentials readable. Verified: no .env -> compose fails closed naming the missing variable; with a generated .env the stack is healthy, /v1/models returns 200 for the generated key, 401 for sk-1234 and 401 unauthenticated, /ui/ serves, and the key still works after a restart. --- docker/README.md | 1 + docker/docker-compose.quickstart.yml | 11 ++++++----- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docker/README.md b/docker/README.md index 787866ce35a..376dc7b2d97 100644 --- a/docker/README.md +++ b/docker/README.md @@ -9,6 +9,7 @@ This guide provides instructions for building and running the LiteLLM applicatio > > ```bash > curl -sSLO https://github.com/BerriAI/litellm/raw/main/docker/docker-compose.quickstart.yml +> printf 'LITELLM_MASTER_KEY=sk-%s\nLITELLM_SALT_KEY=sk-%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env > docker compose -f docker-compose.quickstart.yml up -d > ``` diff --git a/docker/docker-compose.quickstart.yml b/docker/docker-compose.quickstart.yml index 7c849c759f0..11631603a72 100644 --- a/docker/docker-compose.quickstart.yml +++ b/docker/docker-compose.quickstart.yml @@ -3,19 +3,20 @@ # https://docs.litellm.ai/docs/proxy/docker_quick_start # # curl -sSLO https://github.com/BerriAI/litellm/raw/main/docker/docker-compose.quickstart.yml +# printf 'LITELLM_MASTER_KEY=sk-%s\nLITELLM_SALT_KEY=sk-%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env # docker compose -f docker-compose.quickstart.yml up -d # -# The credentials below are placeholders for local evaluation. Before any real -# use, set LITELLM_MASTER_KEY and LITELLM_SALT_KEY to long random values and -# pin the image to a specific release tag. +# Compose reads .env from this directory. Keep it: regenerating LITELLM_SALT_KEY +# makes credentials already stored in the database unreadable. For anything +# beyond local evaluation, pin the image to a specific release tag. services: litellm: image: docker.litellm.ai/berriai/litellm:main-stable ports: - "4000:4000" environment: - LITELLM_MASTER_KEY: sk-1234 - LITELLM_SALT_KEY: sk-XXXXXXXXXXXXXXXX + LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY:?set it in .env - see the header of this file} + LITELLM_SALT_KEY: ${LITELLM_SALT_KEY:?set it in .env - see the header of this file} DATABASE_URL: postgresql://litellm:litellm@db:5432/litellm STORE_MODEL_IN_DB: "True" depends_on: