diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..74a9f94
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,10 @@
+# Dostalgia — Environment Configuration
+# Copy this file to .env and fill in your values:
+#   cp .env.example .env
+
+# Twitch Client ID for IGDB metadata auto-scrape.
+# Get yours at https://dev.twitch.tv/console/apps → Create Application
+# (Set OAuth Redirect URL to http://localhost, Category to "Other")
+# Optional — IGDB features gracefully skip if not set.
+# TWITCH_CLIENT_ID=your_client_id_here
+# TWITCH_CLIENT_SECRET=your_client_secret_here
diff --git a/.gitignore b/.gitignore
index 397063d..22cb277 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,6 +2,10 @@
 node_modules/
 frontend/node_modules/
 
+# Environment — secrets
+.env
+.env.local
+
 # Built output
 frontend/dist/
 dist/
diff --git a/README.md b/README.md
index 050ce4d..ceb0bd0 100644
--- a/README.md
+++ b/README.md
@@ -4,14 +4,29 @@ A nostalgic DOS game hub. Upload your old DOS games, scrape artwork, and play th
 
 ## Quick Start
 
+### With Docker Compose (easiest)
+
 ```bash
-# Build and run with Docker
-docker build -t dostalgia .
-docker run -p 8765:8765 -v $(pwd)/data:/data dostalgia
+# 1. (Optional) Enable IGDB metadata auto-scrape
+cp .env.example .env
+# Edit .env with your Twitch credentials (see IGDB section below)
+
+# 2. Build & run
+docker compose up -d
 ```
 
 Open http://localhost:8765
 
+### With Docker
+
+```bash
+docker build -t dostalgia .
+docker run -p 8765:8765 -v $(pwd)/data:/data \
+  -e TWITCH_CLIENT_ID=your_id \
+  -e TWITCH_CLIENT_SECRET=your_secret \
+  dostalgia
+```
+
 ## Development (without Docker)
 
 Terminal 1 — Frontend dev server:
@@ -66,3 +81,22 @@ java -jar target/quarkus-app/quarkus-run.jar
   "ready": true
 }
 ```
+
+## IGDB Metadata (Optional)
+
+Dostalgia can auto-populate game metadata (year, genre, developer, cover art, screenshots, videos) from the [IGDB](https://www.igdb.com/) database. This requires a Twitch API application.
+
+**Setup:**
+
+1. Go to https://dev.twitch.tv/console/apps → **Register Your Application**
+2. Name: `Dostalgia` (or anything), OAuth Redirect URL: `http://localhost`, Category: **Other**
+3. Copy the **Client ID** and generate a **Client Secret**
+4. Provide them via environment variables:
+
+| Method | How |
+|--------|-----|
+| Docker run | `-e TWITCH_CLIENT_ID=xxx -e TWITCH_CLIENT_SECRET=yyy` |
+| Docker Compose | Copy `.env.example` to `.env` and fill in the values |
+| Local dev | `export TWITCH_CLIENT_ID=xxx TWITCH_CLIENT_SECRET=yyy` |
+
+IGDB features degrade gracefully — if credentials aren't set, uploads and metadata editing still work, just without auto-scrape.
diff --git a/docker-compose.yml b/docker-compose.yml
index f5a3e71..edd9be9 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -6,9 +6,8 @@ services:
       - "8765:8765"
     volumes:
       - ./data:/data
+    env_file:
+      - .env
     environment:
       - DOSTALGIA_DATA_DIR=/data
-      # IGDB credentials — set these for auto-scrape to work:
-      # - TWITCH_CLIENT_ID=your_client_id
-      # - TWITCH_CLIENT_SECRET=your_client_secret
     restart: unless-stopped