Skip to content

Update README.md #30

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Skulldorom merged 1 commit into from
Jul 26, 2026
Merged

Update README.md #30

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 65 additions & 23 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand Down Expand Up @@ -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 <token>" \
"http://localhost:5000/freshrss/unread?n=10&category=Tech"

# Without auth (token not set):
Expand All @@ -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 <token>
```

## Testing
Expand All @@ -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 <token>
display: dynamic-list
mappings:
name: feed
label: display
```

# Docker
Expand All @@ -95,19 +96,32 @@ 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 <token>`. |
| 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 <token>`. |

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

> [!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 <username>`.

`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
Expand All @@ -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 <token> on protected endpoints.
RSS_API_TOKEN: ${RSS_API_TOKEN:-}
Expand Down Expand Up @@ -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 <username>
```

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=<your-freshrss-api-password>
```

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:
Expand All @@ -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
Expand Down
Loading