diff --git a/docker-compose.yaml b/docker-compose.yaml
index dccb267..2aa38ae 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -7,7 +7,9 @@ services:
       target: bolt-ai-production
     ports:
       - '5173:5173'
-    env_file: '.env.local'
+    env_file: 
+      - '.env'
+      - '.env.local'
     environment:
       - NODE_ENV=production
       - COMPOSE_PROFILES=production
@@ -37,7 +39,9 @@ services:
     image: bolt-ai:development
     build:
       target: bolt-ai-development
-    env_file: '.env.local'
+    env_file: 
+      - '.env'
+      - '.env.local'
     environment:
       - NODE_ENV=development
       - VITE_HMR_PROTOCOL=ws
diff --git a/docs/docs/CONTRIBUTING.md b/docs/docs/CONTRIBUTING.md
index 400bb32..63ee56d 100644
--- a/docs/docs/CONTRIBUTING.md
+++ b/docs/docs/CONTRIBUTING.md
@@ -95,11 +95,20 @@ Interested in maintaining and growing the project? Fill out our [Contributor App
      OPENAI_API_KEY=XXX
      ...
      ```
-  3. Optionally set:
+  3. **For Docker users**: Run the setup script or manually copy `.env.local` to `.env`:
+     ```bash
+     # Option 1: Use the setup script
+     ./scripts/setup-env.sh
+     
+     # Option 2: Manual copy
+     cp .env.local .env
+     ```
+     Docker Compose requires `.env` for variable substitution.
+  4. Optionally set:
      - Debug level: `VITE_LOG_LEVEL=debug`
      - Context size: `DEFAULT_NUM_CTX=32768`
 
-**Note**: Never commit your `.env.local` file to version control. It’s already in `.gitignore`.
+**Note**: Never commit your `.env.local` or `.env` files to version control. They're already in `.gitignore`.
 
 ### 2️⃣ Run Development Server
 
diff --git a/docs/docs/index.md b/docs/docs/index.md
index e5f9908..66698af 100644
--- a/docs/docs/index.md
+++ b/docs/docs/index.md
@@ -99,7 +99,11 @@ ANTHROPIC_API_KEY=XXX
 
 Once you've set your keys, you can proceed with running the app. You will set these keys up during the initial setup, and you can revisit and update them later after the app is running.
 
-**Note**: Never commit your `.env.local` file to version control. It’s already included in the `.gitignore`.
+**Important for Docker users**: Docker Compose needs a `.env` file for variable substitution. After creating `.env.local`:
+- Run `./scripts/setup-env.sh` to automatically sync the files, or  
+- Manually copy: `cp .env.local .env`
+
+**Note**: Never commit your `.env.local` or `.env` files to version control. They're already included in the `.gitignore`.
 
 #### 2. Configure API Keys Directly in the Application
 
diff --git a/scripts/setup-env.sh b/scripts/setup-env.sh
new file mode 100755
index 0000000..e302af9
--- /dev/null
+++ b/scripts/setup-env.sh
@@ -0,0 +1,41 @@
+#!/bin/bash
+
+# Setup script for Docker environment variables
+# This script helps resolve the issue where .env.local is not being loaded in Docker
+
+echo "🔧 Setting up environment files for Docker..."
+
+# Check if .env.local exists
+if [ -f ".env.local" ]; then
+    echo "✅ Found .env.local file"
+    
+    # Create symlink or copy to .env for Docker Compose
+    if [ ! -f ".env" ] || [ ".env" -ot ".env.local" ]; then
+        echo "📋 Copying .env.local to .env for Docker Compose compatibility..."
+        cp .env.local .env
+        echo "✅ Environment file synced"
+    else
+        echo "ℹ️  .env file already up to date"
+    fi
+else
+    echo "⚠️  No .env.local file found"
+    
+    # Check if .env.example exists and offer to copy it
+    if [ -f ".env.example" ]; then
+        echo "📋 Found .env.example file"
+        read -p "Would you like to create .env.local from .env.example? (y/n) " -n 1 -r
+        echo
+        if [[ $REPLY =~ ^[Yy]$ ]]; then
+            cp .env.example .env.local
+            cp .env.example .env
+            echo "✅ Created .env.local and .env from .env.example"
+            echo "📝 Please edit .env.local with your API keys"
+        fi
+    fi
+fi
+
+echo "✨ Environment setup complete!"
+echo ""
+echo "📚 Note: Docker Compose reads both .env and .env.local files"
+echo "   - .env is used for variable substitution in docker-compose.yaml"
+echo "   - .env.local is passed to the container for runtime variables"
\ No newline at end of file