diff --git a/.gitignore b/.gitignore
index 4d13c42..c9dbc44 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,4 +4,5 @@ config/config.local.php
 logs/app.log
 agent-prompts
 .env
+docker-compose.yml
 ~*
\ No newline at end of file
diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
index fc3d36e..4847f52 100644
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -115,6 +115,14 @@ CMD ["php", "-S", "0.0.0.0:8080", "-t", "public"]
 ```
 
 ### Docker Compose
+Use the example template as the base for a local override:
+
+```bash
+cp docker-compose.example.yml docker-compose.yml
+```
+
+Then adapt the local values as needed:
+
 ```yaml
 services:
   password-generator:
@@ -132,6 +140,7 @@ services:
       CORS_METHODS: "GET,POST,OPTIONS"
       CORS_HEADERS: "Content-Type,Authorization"
     volumes:
+      - ./.env:/var/www/html/.env:ro
       - ./logs:/var/www/html/logs
     restart: unless-stopped
 ```
diff --git a/Dockerfile b/Dockerfile
index ddbd66e..df44202 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -28,7 +28,7 @@ COPY . /var/www/html/
 RUN composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist \
     && mkdir -p logs \
     && chmod 755 logs \
-    && cp -n .env.example .env \
+    && if [ ! -f .env ]; then cp .env.example .env; fi \
     && chown -R www-data:www-data /var/www/html
 
 EXPOSE 8080
diff --git a/README.md b/README.md
index 930b003..df8f385 100644
--- a/README.md
+++ b/README.md
@@ -219,10 +219,11 @@ docker run --rm -p 8080:8080 --name password-generator password-generator:latest
 
 ### Docker Compose (project-local setup)
 
-The repository includes a project-specific Compose file for local development and testing.
+The repository ships a compose template rather than a committed local override. Copy it to a host-specific file before running locally.
 
 ```bash
 cp .env.example .env
+cp docker-compose.example.yml docker-compose.yml
 cp config/config.example.json config/config.json
 mkdir -p logs
 
diff --git a/docker-compose.yml b/docker-compose.example.yml
similarity index 95%
rename from docker-compose.yml
rename to docker-compose.example.yml
index 55f9dc8..4b5ceef 100644
--- a/docker-compose.yml
+++ b/docker-compose.example.yml
@@ -20,6 +20,7 @@ services:
       CORS_METHODS: "GET,POST,OPTIONS"
       CORS_HEADERS: "Content-Type,Authorization"
     volumes:
+      - ./.env:/var/www/html/.env:ro
       - ./logs:/var/www/html/logs
       - ./config/config.json:/var/www/html/config/config.json:ro
     healthcheck:
diff --git a/public/index.php b/public/index.php
index 3993de0..ccef715 100644
--- a/public/index.php
+++ b/public/index.php
@@ -9,9 +9,14 @@ use Slim\Factory\AppFactory;
 
 require __DIR__ . '/../vendor/autoload.php';
 
-// Load environment variables
-$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/../');
-$dotenv->load();
+// Load environment variables when a project .env file is present.
+// Docker can provide these via env_file/environment as well; in that case
+// we should not crash if the file is not mounted into the container.
+$dotenvPath = __DIR__ . '/../';
+if (is_file($dotenvPath . '.env')) {
+    $dotenv = Dotenv\Dotenv::createImmutable($dotenvPath);
+    $dotenv->safeLoad();
+}
 
 // Build DI container
 $containerBuilder = new ContainerBuilder();