From 7b312a94522895f95d5ae90d0d16e46b23b01682 Mon Sep 17 00:00:00 2001
From: Skulldorom <51134009+Skulldorom@users.noreply.github.com>
Date: Mon, 20 Jul 2026 12:40:46 +0300
Subject: [PATCH] Require explicit FreshRSS connection configuration

---
 .env.example       | 11 ++++++-
 README.md          | 73 ++++++++++++++++++++++++++++++++++++++++++----
 docker-compose.yml |  8 +++--
 3 files changed, 82 insertions(+), 10 deletions(-)

diff --git a/.env.example b/.env.example
index 25733b8..32810b3 100644
--- a/.env.example
+++ b/.env.example
@@ -1,4 +1,13 @@
 # FreshRSS API credentials
-FRESHRSS_HOST=http://localhost:8020
+# Choose the FRESHRSS_HOST appropriate for your deployment. See README.md.
+# FreshRSS service in the same Compose project/network:
+FRESHRSS_HOST=http://freshrss
+# Docker Desktop (FreshRSS published on host port 8020):
+# FRESHRSS_HOST=http://host.docker.internal:8020
+# Linux (use the host's explicit address):
+# FRESHRSS_HOST=http://192.168.1.10:8020
+# Linux with the host-gateway extra_hosts mapping shown in README.md:
+# FRESHRSS_HOST=http://host.docker.internal:8020
+
 FRESHRSS_USER=your-freshrss-username
 FRESHRSS_PASS=your-freshrss-password
diff --git a/README.md b/README.md
index 3349281..5acd3e4 100644
--- a/README.md
+++ b/README.md
@@ -50,22 +50,83 @@ Example of services.yaml:
 
 # Docker
 
-You can configure environment variables directly in `docker-compose.yml` instead of using a `.env` file. Default values are provided, but you can override them as needed:
+Copy the example environment file and set all three required values:
 
+```bash
+cp .env.example .env
+```
+
+`FRESHRSS_HOST` must be a URL that is reachable **from the API container**. Do
+not use `localhost`: inside the container that name refers to the API container
+itself, not FreshRSS. Compose validates `FRESHRSS_HOST`, `FRESHRSS_USER`, and
+`FRESHRSS_PASS` before creating the container, so an unset or empty value
+produces a clear configuration error instead of entering a restart loop.
+
+Choose one of the following host configurations.
+
+### FreshRSS in the same Compose project
+
+When FreshRSS is a service on the same Compose network, use its service name.
+For example, if the service is named `freshrss`:
+
+```yaml
+services:
+  freshrss:
+    image: freshrss/freshrss:latest
+    # Add the FreshRSS volumes and other settings required by your deployment.
+
+  custom-api:
+    image: ghcr.io/skulldorom/rss-api:latest
+    environment:
+      FRESHRSS_HOST: http://freshrss
+      FRESHRSS_USER: ${FRESHRSS_USER:?Set FRESHRSS_USER in .env}
+      FRESHRSS_PASS: ${FRESHRSS_PASS:?Set FRESHRSS_PASS in .env}
+```
+
+Equivalently, keep the provided Compose file and set this in `.env`:
+
+```dotenv
+FRESHRSS_HOST=http://freshrss
 ```
-environment:
-	FRESHRSS_USER: "user"
-	FRESHRSS_PASS: "password"
+
+### FreshRSS on the Docker Desktop host
+
+Docker Desktop provides `host.docker.internal` for reaching a service exposed
+by the host. If FreshRSS is published on host port `8020`, use:
+
+```dotenv
+FRESHRSS_HOST=http://host.docker.internal:8020
 ```
 
-Edit these values in your `docker-compose.yml` to match your setup.
+### FreshRSS on a Linux host
+
+On Linux, set the host's address explicitly (replace the example address with
+one reachable from Docker):
+
+```dotenv
+FRESHRSS_HOST=http://192.168.1.10:8020
+```
+
+Alternatively, map Docker's host gateway in `docker-compose.yml` and then use
+the same hostname as the Docker Desktop example:
+
+```yaml
+services:
+  custom-api:
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+```
+
+```dotenv
+FRESHRSS_HOST=http://host.docker.internal:8020
+```
 
 ## Running with Docker Compose
 
 You can run the API using the pre-built image from GitHub Container Registry:
 
 ```bash
-docker-compose up
+docker compose up
 ```
 
 This uses the image `ghcr.io/skulldorom/rss-api:latest`.
diff --git a/docker-compose.yml b/docker-compose.yml
index 1b08bab..289a638 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -6,7 +6,9 @@ services:
     ports:
       - "5000:5000"
     environment:
-      FRESHRSS_HOST: "${FRESHRSS_HOST:-http://localhost:8020}"
-      FRESHRSS_USER: "${FRESHRSS_USER}"
-      FRESHRSS_PASS: "${FRESHRSS_PASS}"
+      # Required interpolation makes Compose stop with a useful error before it
+      # creates a container that would otherwise repeatedly restart.
+      FRESHRSS_HOST: "${FRESHRSS_HOST:?Set FRESHRSS_HOST in .env (see README.md)}"
+      FRESHRSS_USER: "${FRESHRSS_USER:?Set FRESHRSS_USER in .env}"
+      FRESHRSS_PASS: "${FRESHRSS_PASS:?Set FRESHRSS_PASS in .env}"
     restart: unless-stopped