diff --git a/.env.example b/.env.example
index efc2542dd..0e16e2c1a 100644
--- a/.env.example
+++ b/.env.example
@@ -12,6 +12,14 @@ SECUSCAN_BIND_PORT=8000
 # SECUSCAN_REDIS_URL=redis://127.0.0.1:6379/0
 # SECUSCAN_CACHE_TTL_SECONDS=30
 
+# PostgreSQL — optional overrides for docker-compose (defaults work for local dev)
+# The default credentials are only reachable on 127.0.0.1. Override them if
+# PostgreSQL will be accessible beyond localhost.
+# Generate a strong password with: python -c "import secrets; print(secrets.token_urlsafe(32))"
+# SECUSCAN_POSTGRES_USER=secuscan
+# SECUSCAN_POSTGRES_DB=secuscan
+# SECUSCAN_POSTGRES_PASSWORD=
+
 # Docker Support
 SECUSCAN_DOCKER_ENABLED=false
 # Docker sandbox network (auto-created if absent; ICC disabled for isolation)
diff --git a/README.md b/README.md
index 8a40b8bcb..359f103a1 100644
--- a/README.md
+++ b/README.md
@@ -173,6 +173,8 @@ cd SecuScan
 docker compose up --build
 ```
 
+The quickstart uses default local-only credentials. For production or any deployment where PostgreSQL is reachable beyond localhost, set `SECUSCAN_POSTGRES_PASSWORD` (and optionally `SECUSCAN_POSTGRES_USER`, `SECUSCAN_POSTGRES_DB`) in a `.env` file before starting. See `.env.example` for details.
+
 Open:
 
 - Frontend: `http://127.0.0.1:5173`
diff --git a/docker-compose.yml b/docker-compose.yml
index 307932d9e..28e1433ac 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -3,15 +3,15 @@ services:
   postgres:
     image: postgres:16-alpine
     environment:
-      POSTGRES_DB: secuscan
-      POSTGRES_USER: secuscan
-      POSTGRES_PASSWORD: secuscan
+      POSTGRES_DB: ${SECUSCAN_POSTGRES_DB:-secuscan}
+      POSTGRES_USER: ${SECUSCAN_POSTGRES_USER:-secuscan}
+      POSTGRES_PASSWORD: ${SECUSCAN_POSTGRES_PASSWORD:-secuscan}
     ports:
       - "127.0.0.1:5432:5432"
     volumes:
       - postgres_data:/var/lib/postgresql/data
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U secuscan -d secuscan"]
+      test: ["CMD-SHELL", "pg_isready -U ${SECUSCAN_POSTGRES_USER:-secuscan} -d ${SECUSCAN_POSTGRES_DB:-secuscan}"]
       interval: 10s
       timeout: 5s
       retries: 5
@@ -43,7 +43,7 @@ services:
     environment:
       - SECUSCAN_BIND_ADDRESS=0.0.0.0   # fix: was 127.0.0.1, unreachable inside Docker
       - SECUSCAN_BIND_PORT=8081
-      - SECUSCAN_POSTGRES_DSN=postgresql://secuscan:secuscan@postgres:5432/secuscan
+      - SECUSCAN_POSTGRES_DSN=postgresql://${SECUSCAN_POSTGRES_USER:-secuscan}:${SECUSCAN_POSTGRES_PASSWORD:-secuscan}@postgres:5432/${SECUSCAN_POSTGRES_DB:-secuscan}
       - SECUSCAN_REDIS_URL=redis://redis:6379/0
       - SECUSCAN_PLUGINS_DIR=/app/plugins
     depends_on:
diff --git a/docs/windows_contributor_guide.md b/docs/windows_contributor_guide.md
index f41ac02ba..8ac744787 100644
--- a/docs/windows_contributor_guide.md
+++ b/docs/windows_contributor_guide.md
@@ -222,6 +222,11 @@ docker compose up --build
 If `docker compose` fails even though Docker Desktop is installed, open Docker
 Desktop first and wait until the engine reports it is running.
 
+The quickstart uses default local-only credentials. To set custom PostgreSQL
+credentials (recommended for production), create a `.env` file in the project
+root before running `docker compose up --build`. See `.env.example` for the
+available variables.
+
 ---
 
 ## Common Windows Troubleshooting