From 72b4d3d28ba2e1650c00edefea4347084f3adcc5 Mon Sep 17 00:00:00 2001 From: Skulldorom <51134009+Skulldorom@users.noreply.github.com> Date: Sun, 26 Jul 2026 14:19:35 +0300 Subject: [PATCH] Update README.md --- README.md | 88 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 65 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index c770418..1cd6351 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@ Using their [Custom API integration](https://gethomepage.dev/widgets/services/cu ## API Documentation The API provides interactive documentation at: + - Swagger UI: `http://localhost:5000/docs` - ReDoc: `http://localhost:5000/redoc` @@ -41,7 +42,7 @@ printf 'RSS_API_TOKEN=%s\n' "$RSS_API_TOKEN" >> .env ```bash # With auth enabled (token set): curl \ - -H "Authorization: Bearer your-secret-token" \ + -H "Authorization: Bearer " \ "http://localhost:5000/freshrss/unread?n=10&category=Tech" # Without auth (token not set): @@ -52,7 +53,7 @@ When auth is enabled, clients such as Homepage must send the same header: ```yaml headers: - Authorization: Bearer your-secret-token + Authorization: Bearer ``` ## Testing @@ -68,21 +69,21 @@ GitHub Actions runs these tests for pull requests and before publishing the Dock Example of services.yaml: -``` +```yaml - Updates: - icon: github.png - href: http://192.168.0.11:5000 - siteMonitor: http://192.168.0.11:5000/freshrss/unread - widget: - type: customapi - name: Unread RSS - url: http://192.168.0.11:5000/freshrss/unread - headers: - Authorization: Bearer your-secret-token - display: dynamic-list - mappings: - name: feed - label: display + icon: github.png + href: http://192.168.0.11:5000 + siteMonitor: http://192.168.0.11:5000/freshrss/unread + widget: + type: customapi + name: Unread RSS + url: http://192.168.0.11:5000/freshrss/unread + headers: + Authorization: Bearer + display: dynamic-list + mappings: + name: feed + label: display ``` # Docker @@ -95,12 +96,12 @@ cp .env.example .env Configure these environment variables in `.env` or your Compose environment: -| Variable | Required | Default if unset | Description | -| --- | --- | --- | --- | -| `FRESHRSS_HOST` | Yes | No default; app startup fails. | FreshRSS base URL reachable from the API container. The example `.env` uses `http://freshrss` for a same-network Compose service. | -| `FRESHRSS_USER` | Yes | No default; app startup fails. | FreshRSS username used for Google Reader API login. | -| `FRESHRSS_PASS` | Yes | No default; app startup fails. | FreshRSS password used for Google Reader API login. | -| `RSS_API_TOKEN` | No | Empty/unset; bearer auth disabled. | Optional bearer token for this API. When set, protected endpoints require `Authorization: Bearer `. | +| Variable | Required | Default if unset | Description | +| --------------- | -------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `FRESHRSS_HOST` | Yes | No default; app startup fails. | FreshRSS base URL reachable from the API container. The example `.env` uses `http://freshrss` for a same-network Compose service. | +| `FRESHRSS_USER` | Yes | No default; app startup fails. | FreshRSS username used for Google Reader API login. | +| `FRESHRSS_PASS` | Yes | No default; app startup fails. | FreshRSS API/GReader password used for Google Reader API login. This is **not** the normal FreshRSS web UI password. Create or set the API password in FreshRSS user settings and use that value here. | +| `RSS_API_TOKEN` | No | Empty/unset; bearer auth disabled. | Optional bearer token for this API. When set, protected endpoints require `Authorization: Bearer `. | `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 @@ -108,6 +109,19 @@ 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. +> [!IMPORTANT] +> `FRESHRSS_PASS` must be the FreshRSS API/GReader password, not your normal +> FreshRSS web login password. FreshRSS stores these separately. If you use the +> web login password here, FreshRSS may reject the login with `401` and log +> `Password API mismatch for user `. + +`RSS_API_TOKEN` is different from `FRESHRSS_PASS`: + +| Value | Used by | Purpose | +| --------------- | -------------------- | -------------------------------------------------------------------------------------------- | +| `FRESHRSS_PASS` | `rss-api` → FreshRSS | Logs into FreshRSS through the Google Reader API. Must be the FreshRSS API/GReader password. | +| `RSS_API_TOKEN` | Client → `rss-api` | Protects this API's endpoints with bearer authentication. Optional. | + Choose one of the following host configurations. ### FreshRSS in the same Compose project @@ -126,6 +140,7 @@ services: environment: FRESHRSS_HOST: http://freshrss FRESHRSS_USER: ${FRESHRSS_USER:?Set FRESHRSS_USER in .env} + # Must be the FreshRSS API/GReader password, not the web UI password. FRESHRSS_PASS: ${FRESHRSS_PASS:?Set FRESHRSS_PASS in .env} # Optional: require Authorization: Bearer on protected endpoints. RSS_API_TOKEN: ${RSS_API_TOKEN:-} @@ -169,6 +184,33 @@ services: FRESHRSS_HOST=http://host.docker.internal:8020 ``` +## Troubleshooting + +### FreshRSS login fails with status 401 + +If API requests fail with: + +```text +FreshRSS login failed with status 401 +``` + +and FreshRSS logs show: + +```text +Password API mismatch for user +``` + +then `FRESHRSS_PASS` is probably set to the normal FreshRSS web login password. + +Fix it by creating or setting the FreshRSS API/GReader password in FreshRSS user +settings, then update `.env`: + +```dotenv +FRESHRSS_PASS= +``` + +Restart the API container after changing `.env`. + ## Running with Docker Compose You can run the API using the pre-built image from GitHub Container Registry: @@ -190,7 +232,7 @@ If you want to override it in `docker-compose.yml`, you can add a service-level Go to the location where you ran git clone, `cd rss-api` -``` +```bash docker compose down git pull origin main docker compose up -d