docs: rewrite Docker quickstart as a visual UI-first deployment guide

[yassin-berriai]

Resolves LIT-4222.

The Docker getting-started page (docs/proxy/docker_quick_start.md) was an 877 line tutorial that led with a curl-piped install script, a CLI wizard, uv commands, and three hand-written config files before the reader ever saw the product. The proxy is an out-of-the-box gateway, so this PR rewrites the page as a visual quickstart built around how the product actually onboards: start one Docker Compose stack, then do everything in the Admin UI.

The new page is about 220 lines. It inlines a minimal two-service compose file (litellm-database plus Postgres, no config.yaml at all), then walks through the UI with real screenshots captured from a live v1.91.0 deployment: log in with the default credentials shown on the login page itself, add a model from the provider catalog, verify it with Test Connect, send a test message in the Playground, create a virtual key, and call the gateway with any OpenAI SDK. A short GIF shows the whole flow. The old content that still matters survives in condensed form: a no-database docker run variant with a config file, the salt key warning, and next-step links.

Every step was validated on a live gateway brought up with the exact compose file in the page: the UI login defaults, UI model add with both a pasted key and an os.environ reference, Test Connect against the real OpenAI API, a Playground round trip, and the final curl with a freshly minted virtual key returning the response embedded in the doc.

The deploy reference itself gets the same treatment. The old docs/proxy/deploy.md was an unstaged wall: registry notes, uv installs, a cosign section duplicating the image security guide, raw manifests, Helm, Terraform pointers, DB and Redis matrices, and eight numbered "advanced settings" all on one page. It is now replaced by the staged cloud deployment guide that previously lived at deploy_cloud.md (architecture selector, core configuration, data stores per cloud, Helm, Terraform, UI-first verify), kept at the /docs/proxy/deploy route with a client redirect from /docs/proxy/deploy_cloud. The raw Kubernetes manifest survives as a collapsed section on the new page, Render and Railway become a short Other Platforms section, and deployment pages no longer carry any litellm CLI or uv content. Server tuning content that was buried in deploy.md (SSL flags, Hypercorn, Granian, keepalive, config from S3/GCS, local price map) moves to prod.md as a Server tuning section along with the deployment FAQ; content that merely duplicated other pages (cosign verification, non-root image, IAM RDS auth, robots blocking) is dropped in favor of the pages that own it.

prod.md gets the same restructure: the emoji title and the 1-through-10 numbered grab-bag become thematic sections (Configuration, Sizing and workers, Redis, Database and migrations, Server tuning, Verify production readiness, Deployment FAQ) with the same content, and the six inbound anchors that pointed at numbered headings (config_settings, multi_region, rollback, deploy) are retargeted; one of them had already gone stale against the old numbering.

microservices_helm.md is deleted as part of the same consolidation; its install steps were already covered by the Deploy page's Helm section and its remaining content was a values reference, so the page redirects to deploy#deploy-with-helm and the values reference now points at the chart's values.yaml in the litellm repo.

Navigation is consolidated to match: Setup & Deployment now reads Deploy, Production, Multi-Region, and the operational references, while the CLI pages (quick_start, cli) move to their own CLI group and debugging/error_diagnosis to a Troubleshooting group. The sidebar entry for the tutorial is relabeled from "Getting Started Tutorial" to "Docker Quickstart", the docs landing page points proxy users at the quickstart instead of a uv install command, and all inbound links and anchors (multi_region, virtual_keys, custom_root_ui, vertex) are retargeted.

The rest of the Setup and Deployment section gets the same treatment, with every rewritten claim verified against the litellm source. health.md goes from a 528 line wall of fifteen near-identical per-mode yaml blocks and zero images to 147 lines: a probe-endpoint semantics table (adding the /health/liveness alias and correcting the readiness payload, which is now low-detail by default and 503s when the database is down), the Admin UI Health Status tab with a real screenshot as the primary model-health surface, one mode table plus one example, and an operator reference table that fixes a stale default (health check max_tokens is 16, not 5). model_management.md goes from a curl-only API reference to a UI-first day-2 operations page with three live screenshots (model list, detail and edit page, credential modal); ui_credentials.md and ui_store_model_db_setting.md fold into it with redirects, and the automation section now documents POST /model/delete, which was previously documented nowhere. master_key_rotations.md is rewritten around a source-verified hazard: the old page's /key/regenerate flow re-encrypts credentials under the new master key unconditionally, while a proxy with LITELLM_SALT_KEY set keeps decrypting with the salt key, so following the old doc on the recommended production setup would make every stored credential unreadable; the new page leads with that warning and gives the correct path for each setup. prod.md drops to under 400 lines by splitting deep server-ops material (Gunicorn, Hypercorn, Granian, worker recycling detail, TLS at the proxy, keepalive, config from object storage) into a new server_tuning.md page, and its Redis section now explains what Redis is for instead of repeating a stale claim that redis_url costs 80 RPS; the same stale claim is removed from benchmarks.md. worker_startup_hooks.md moves to the Create Custom Plugins category where it belongs. All inbound links and anchors across docs, release notes, and provider pages are retargeted.

The Architecture category gets the same treatment and is reconciled with Setup and Deployment. It shrinks from twelve pages to four pure how-it-works pages: Life of a Request (absorbing the router and image-handling diagram stubs), Multi-Tenant Architecture (cut from 710 lines to 74 by absorbing the user-hierarchy stub and replacing sections that duplicated Access Control, Service Accounts, Team Budgets, Self-Serve, and Logging with cross-links), How Key-Based Auth Works, and What is stored in the DB. The operational pages move to where operators look for them: db_read_replica, db_deadlocks (retitled to stop colliding with the HA control plane page), and the HA control plane join Setup and Deployment; jwt_auth_arch joins Authentication; spend_logs_deletion joins Spend Tracking. The three absorbed stubs redirect to their new sections.

Source verification during this pass fixed real documentation bugs: the image-handling cache claim (10 images in memory and a 50MB per-image download cap, not a 1MB cache), the rate limiter link (now the v3 hook), the read-replica IAM env var claim, the spend-log partition cleanup switch (requires use_spend_logs_partitioning, detection alone does not enable it), a stale HA login flow description (the UI exchanges a single-use code, it does not receive the JWT directly), and a security-relevant correction in key auth: a key carrying all-team-models with no team_id resolves to unrestricted access rather than the denial the old page claimed. A verified operational caveat was added to the HA page: without Redis, the login-code exchange can land on a different pod and fail.

The Architecture pages' raster diagrams (litellm_gateway, router_architecture, image_handling, litellm_user_heirarchy) are replaced with themed React diagram components in the same visual system the multi-region and cloud deployment pages use: a request-lifecycle diagram with the gateway's numbered stages and its Postgres/Redis dependencies, a router fallback/retry flow, an image-URL decision flow, and a tenancy hierarchy used by both multi_tenant_architecture and access_control. The four PNGs are deleted.

npm run build passes with no broken links into any page this PR touches.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	Jul 8, 2026 1:34pm