Require explicit FreshRSS host and credentials; remove localhost fallback

.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

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`.

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