From e4be5546a24b0c846d8ba8719aa6134ea6706464 Mon Sep 17 00:00:00 2001
From: g0ldyy <153996346+g0ldyy@users.noreply.github.com>
Date: Fri, 2 Jan 2026 15:10:48 +0100
Subject: [PATCH] docs: clarify `.env` file setup instructions and add a
 warning for `FASTAPI_WORKERS` configuration

---
 .env-sample | 7 ++++++-
 README.md   | 2 +-
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/.env-sample b/.env-sample
index 47f94f8..8cd1adf 100644
--- a/.env-sample
+++ b/.env-sample
@@ -5,9 +5,14 @@
 #  ██║     ██║   ██║██║╚██╔╝██║██╔══╝     ██║     #
 #  ╚██████╗╚██████╔╝██║ ╚═╝ ██║███████╗   ██║     #
 #   ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚══════╝   ╚═╝     #
+#=================================================#
 #          Thank you for using Comet! 🚀          #
 #=================================================#
 
+# ⚠️ IMPORTANT: DO NOT copy the entire content of this file to your .env file.
+# Only copy and modify the variables you need to change.
+# The default values shown in this file are automatically loaded by Comet.
+
 # ============================== #
 # Stremio Addon Configuration    #
 # ============================== #
@@ -19,7 +24,7 @@ ADDON_NAME=Comet
 # ============================== #
 FASTAPI_HOST=0.0.0.0
 FASTAPI_PORT=8000
-FASTAPI_WORKERS=1 # set to -1 for auto-scaling (min((os.cpu_count() or 1) * 2 + 1, 12))
+FASTAPI_WORKERS=1 # DO NOT change this if you don't know what you are doing. Setting this to -1 will spawn a worker for each CPU core, which can consume several GBs of RAM and cause high CPU usage.
 USE_GUNICORN=True # Will use uvicorn if False or if on Windows
 GUNICORN_PRELOAD_APP=True # Set to False to start workers without preloading the app (reduces startup cost but requires schema to exist)
 
diff --git a/README.md b/README.md
index 5ea2862..e997268 100644
--- a/README.md
+++ b/README.md
@@ -51,7 +51,7 @@ ElfHosted offer "one-click" [private Comet instances](https://elfhosted.com/app/
 
 ### With Docker Compose
 - Copy *deployment/docker-compose.yml* in a directory
-- Copy *.env-sample* to *.env* in the same directory and keep only the variables you wish to modify, also remove all comments
+- Create a `.env` file in the same directory and add only the variables you wish to modify. All other variables will use the default values from `.env-sample`.
 - Pull the latest version from docker hub
     ```sh
       docker compose pull