From 3e726bb19cd446c1a36c596bf5a06dc88352afc2 Mon Sep 17 00:00:00 2001
From: Misbah Syed <35427888+misbahsy@users.noreply.github.com>
Date: Tue, 29 Sep 2026 01:21:35 -0700
Subject: [PATCH] fix(quickstart): address review findings on reinstall, ports,
 gitignore, and binding

Stop with instructions instead of generating a new password when a database volume from an earlier install is still there, since Postgres keeps the original password

Keep port 4000 for an existing .env that has no saved port, and only search for a free port on fresh installs

Only write the catch-all .gitignore into a folder the script created, and warn instead of writing into a folder that already existed

Add LITELLM_BIND to the compose port mapping. It is empty by default, so existing installs keep "4000:4000", and the script sets it to 127.0.0.1: so new installs listen on this machine only
---
 docker/docker-compose.quickstart.yml |  4 ++-
 scripts/quickstart.sh                | 47 +++++++++++++++++++++++-----
 2 files changed, 42 insertions(+), 9 deletions(-)

diff --git a/docker/docker-compose.quickstart.yml b/docker/docker-compose.quickstart.yml
index 4181f7b60d5..a1d47e323ff 100644
--- a/docker/docker-compose.quickstart.yml
+++ b/docker/docker-compose.quickstart.yml
@@ -13,7 +13,9 @@ services:
   litellm:
     image: docker.litellm.ai/berriai/litellm:main-stable
     ports:
-      - "${LITELLM_PORT:-4000}:4000"
+      # LITELLM_BIND is empty by default, so this stays "4000:4000". The quickstart
+      # script sets it to "127.0.0.1:" so new installs listen on this machine only.
+      - "${LITELLM_BIND:-}${LITELLM_PORT:-4000}:4000"
     environment:
       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}
diff --git a/scripts/quickstart.sh b/scripts/quickstart.sh
index 44921455157..b7829552515 100755
--- a/scripts/quickstart.sh
+++ b/scripts/quickstart.sh
@@ -10,6 +10,9 @@
 #   LITELLM_DIR      folder to install into (skips the folder question)
 #   LITELLM_PORT     port for the gateway (default 4000, or the next free one)
 #
+# New installs listen on this machine only (127.0.0.1). To reach the gateway
+# from other machines, remove LITELLM_BIND from .env and put it behind TLS.
+#
 # Keys and the database password are random (openssl rand), written only to
 # .env with permissions 600, and never printed. Needs Docker with Compose v2.
 # Everything runs inside main(), so a partial download runs nothing.
@@ -144,11 +147,19 @@ pick_folder() {
       "$here_dir   this folder"
     if [ "$CHOICE" = 2 ]; then DIR="$here_dir"; else DIR="$home_dir"; fi
   fi
+  created=0
+  [ -d "$DIR" ] || created=1
   mkdir -p "$DIR"
   cd "$DIR"
   DIR="$(pwd)"
-  # Keeps the folder out of git if it sits inside a repository.
-  [ -f .gitignore ] || printf '*\n' >.gitignore
+  if [ "$created" = 1 ]; then
+    # A folder this script made holds only its own files, so keep all of it out of git.
+    printf '*\n' >.gitignore
+  elif command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1 &&
+    ! git check-ignore -q .env 2>/dev/null; then
+    # Never write ignore rules into a folder that already existed, such as a repository root.
+    echo "Note: $DIR/.env will hold your keys and is not ignored by git. Add .env to your .gitignore."
+  fi
 }
 
 pick_port() {
@@ -158,6 +169,9 @@ pick_port() {
     PORT="$LITELLM_PORT"
   elif [ -n "$saved" ]; then
     PORT="$saved"
+  elif [ -f .env ]; then
+    # An existing install without a saved port runs on the compose default.
+    PORT=4000
   else
     PORT=4000
     while ! port_free "$PORT"; do
@@ -172,6 +186,27 @@ pick_port() {
   export LITELLM_PORT="$PORT"
 }
 
+# Docker names containers and the database volume after the project, so an
+# install outside the home folder gets its own name and never shares a
+# database with another litellm-gateway folder.
+check_new_install() {
+  project=litellm-gateway
+  [ "$DIR" = "$HOME/litellm-gateway" ] || project="litellm-gateway-$(printf '%s' "$DIR" | cksum | cut -d ' ' -f 1)"
+  # Postgres keeps the password it was created with, so a new password over an
+  # old database volume would lock the gateway out. Stop and explain instead.
+  if docker volume inspect "${project}_postgres_data" >/dev/null 2>&1; then
+    cat >&2 <<EOF
+Found a database from an earlier install (Docker volume ${project}_postgres_data)
+but no $DIR/.env with its password.
+
+  Restore that .env file and run this again to keep your models and keys, or
+  delete the old database and start fresh (this removes its models and keys):
+    docker volume rm ${project}_postgres_data
+EOF
+    exit 1
+  fi
+}
+
 open_browser() {
   url="$1"
   menu "Open the admin UI in your browser?" 1 "Yes" "No"
@@ -213,18 +248,14 @@ EOF
 
   echo "LiteLLM quickstart"
   pick_folder
+  [ -f .env ] || check_new_install
   curl -fsSL -o docker-compose.quickstart.yml "$COMPOSE_URL"
   pick_port
 
   if [ -f .env ]; then
     echo "Reusing $DIR/.env, so existing keys and data keep working."
   else
-    # Docker names containers and the database volume after the project, so
-    # an install outside the home folder gets its own name and never shares a
-    # database with another litellm-gateway folder.
-    project=litellm-gateway
-    [ "$DIR" = "$HOME/litellm-gateway" ] || project="litellm-gateway-$(printf '%s' "$DIR" | cksum | cut -d ' ' -f 1)"
-    (umask 077 && printf 'LITELLM_MASTER_KEY=sk-%s\nLITELLM_SALT_KEY=sk-%s\nPOSTGRES_PASSWORD=%s\nLITELLM_PORT=%s\nCOMPOSE_PROJECT_NAME=%s\n' \
+    (umask 077 && printf 'LITELLM_MASTER_KEY=sk-%s\nLITELLM_SALT_KEY=sk-%s\nPOSTGRES_PASSWORD=%s\nLITELLM_PORT=%s\nLITELLM_BIND=127.0.0.1:\nCOMPOSE_PROJECT_NAME=%s\n' \
       "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" "$(openssl rand -hex 24)" "$PORT" "$project" >.env)
     echo "Generated $DIR/.env with your master key, salt key, and database password. Keep this file."
   fi