diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..1448d7c
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,15 @@
+# --- Self-hosted Postgres (Docker) ---
+POSTGRES_USER=routecommerce
+POSTGRES_PASSWORD=change-me-strong-password
+POSTGRES_DB=route_commerce
+# Used by the app and push-migrations.js to talk to the local DB
+DATABASE_URL=postgresql://routecommerce:change-me-strong-password@127.0.0.1:5432/route_commerce?schema=public
+
+# --- Supabase (legacy, can be removed once app is rewired) ---
+NEXT_PUBLIC_SUPABASE_URL=
+NEXT_PUBLIC_SUPABASE_ANON_KEY=
+SUPABASE_SERVICE_ROLE_KEY=
+
+# --- App secrets ---
+MINIMAX_API_KEY=
+MINIMAX_BASE_URL=
diff --git a/.gitignore b/.gitignore
index 81d5216..c49893a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -41,4 +41,6 @@ supabase/.temp/
 
 # IDE / local config
 .mcp.json
-.env*
+
+# Docker / self-hosted Postgres
+db_data/
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..64450d4
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,25 @@
+services:
+  db:
+    image: postgres:16-alpine
+    container_name: route_commerce_db
+    restart: unless-stopped
+    env_file:
+      - .env
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: ${POSTGRES_DB}
+    volumes:
+      - db_data:/var/lib/postgresql/data
+    ports:
+      - "127.0.0.1:5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+
+volumes:
+  db_data:
+    driver: local