eddie/homelab
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

docs(freshrss): Add API troubleshooting documentation

Browse source 
Add comprehensive guides for debugging and resolving FreshRSS API
authentication issues with mobile apps.

Includes:
- API password setup instructions
- iOS app configuration (Reeder, NetNewsWire, etc.)
- Google Reader API vs Fever API comparison
- nginx Authorization header troubleshooting
- Debug logging locations and commands
- Common error patterns and solutions

Covers both successful resolution and known limitations.
This commit is contained in:
Eduardo Figueroa 2025-12-04 18:44:53 +00:00
parent 68632a9662
commit 93b9c883a1
4 changed files with 786 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

189
compose/services/FreshRSS/API-AUTH-FIX.md Normal file
View file

@ -0,0 +1,189 @@
# FreshRSS iOS App Authentication Fix
## The Problem
You're getting "login failed" on your iOS RSS app, but the same credentials work on the website.
**Why:** iOS RSS apps use FreshRSS's **API**, which requires a separate **API password** - NOT your regular web login password.
## The Solution: Generate an API Password
### Step 1: Log into FreshRSS Web Interface
Go to https://feeds.fig.systems and log in with your regular credentials.
### Step 2: Navigate to Profile Settings
1. Click your username (top right)
2. Select **"Configuration"** or **"Settings"**
3. Go to the **"Profile"** tab
### Step 3: Generate API Password
1. Scroll down to **"API management"** section
2. Find **"API password"** field
3. Click **"Generate"** or **"Regenerate"** button
4. Copy the generated API password (it will look like a random string)
Example: `hKm9xP3zQwRt2nLv8YbJ`
### Step 4: Use API Password in iOS App
When configuring your iOS RSS app:
**Username:** `eddie` (your FreshRSS username)
**Password:** `[THE GENERATED API PASSWORD]` ← NOT your web password!
**Server URL:** `https://feeds.fig.systems`
### Common iOS RSS Apps Configuration
#### **Reeder**
- Account Type: FreshRSS
- Server: `https://feeds.fig.systems`
- Username: `eddie`
- Password: [API password]
#### **NetNewsWire**
- Account Type: FreshRSS
- URL: `https://feeds.fig.systems`
- Username: `eddie`
- Password: [API password]
#### **Unread**
- Service: FreshRSS (Google Reader-compatible)
- Server: `https://feeds.fig.systems`
- Username: `eddie`
- Password: [API password]
#### **Fiery Feeds**
- Account Type: FreshRSS
- Server URL: `https://feeds.fig.systems`
- Username: `eddie`
- Password: [API password]
## Verify API is Enabled
If the API password doesn't work, verify API is enabled:
1. Log into FreshRSS web interface
2. Go to **Administration** → **Configuration** → **System**
3. Scroll to **"API (mobile access)"**
4. Ensure **"Enable API"** is checked ✓
5. Click **"Submit"** if you made changes
## Troubleshooting
### Error: "Invalid API password"
**Solution:** Regenerate the API password in FreshRSS web interface and try again.
### Error: "Connection failed" or "Cannot connect to server"
**Check:**
1. URL is exactly: `https://feeds.fig.systems` (no trailing slash)
2. Phone has internet connection
3. Try accessing the URL in Safari/Chrome on the same phone
4. Check if Tinyauth SSO is blocking API access
### SSO/Tinyauth Blocking API Access
FreshRSS has `tinyauth` middleware enabled. This might block API requests if they don't have proper authentication headers.
**Check logs:**
```bash
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/nginx/access.log
```
Look for your iOS app's requests (they'll have User-Agent like "Reeder" or "NetNewsWire").
**If API is being blocked by SSO:**
Option 1: Create a bypass for API endpoint:
```yaml
# In compose.yaml, change:
traefik.http.routers.freshrss.middlewares: tinyauth
# To bypass API paths:
traefik.http.routers.freshrss.middlewares: freshrss-auth
# Add new middleware in Traefik config or labels:
traefik.http.middlewares.freshrss-auth.chain.middlewares: tinyauth-skip-api, tinyauth
```
Option 2: Temporarily disable SSO to test:
```bash
# Comment out in compose.yaml:
# traefik.http.routers.freshrss.middlewares: tinyauth
docker compose up -d
```
### Error: "SSL/Certificate error"
Your FreshRSS uses Let's Encrypt SSL. If iOS app shows certificate errors:
1. Update iOS to latest version
2. Try toggling "Allow self-signed certificates" OFF (you don't need it)
3. Check the URL doesn't have `http://` (must be `https://`)
## View API Logs
### Check what the iOS app is sending:
```bash
# Watch nginx access log
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/nginx/access.log
# Filter for API requests
grep -i "api\|fever\|greader" /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/nginx/access.log | tail -20
```
### Check for authentication errors:
```bash
# PHP errors
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/php_errors.log
# Nginx errors
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/nginx/error.log
```
### Real-time monitoring:
```bash
# Open 3 terminals and watch:
# Terminal 1:
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/nginx/access.log
# Terminal 2:
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/nginx/error.log
# Terminal 3:
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/php_errors.log
# Now try connecting from iOS app
```
## Quick Test: API is Working
Test the API manually:
```bash
# Replace with your actual API password
API_PASSWORD="your-api-password-here"
# Test authentication
curl -s "https://feeds.fig.systems/api/greader.php/reader/api/0/token" \
-u "eddie:$API_PASSWORD" | head -20
# Should return a token, not an error
```
If this works, your API is functional and the issue is with how the iOS app is configured.
## Current Status
✅ **Debug logging enabled** - PHP errors will show in logs
✅ **API enabled** - Checked in config.php (line 20)
⚠️ **SSO might block API** - Tinyauth middleware is active
**Next step:** Generate API password and try it in your iOS app!

121
compose/services/FreshRSS/API-STATUS.md Normal file
View file

@ -0,0 +1,121 @@
# FreshRSS API Status & Next Steps
## Current Configuration
✅ API enabled in FreshRSS
✅ API password set in user profile
✅ Tinyauth SSO removed
✅ Nginx configured with PATH_INFO
✅ Nginx configured to pass Authorization header
✅ Traefik configured to pass host header
## Issue
The API compatibility check still fails: `FAIL get HTTP Authorization header!`
This means the HTTP Authorization header isn't reaching PHP's `$_SERVER['HTTP_AUTHORIZATION']` variable.
## What We've Tried
1. ✅ Removed Tinyauth middleware (was blocking API)
2. ✅ Added fastcgi_param HTTP_AUTHORIZATION to nginx
3. ✅ Added PATH_INFO support (required by FreshRSS API)
4. ✅ Set API password in web interface
5. ✅ Configured Traefik pass host header
## The Root Cause
The nginx → PHP-FPM authorization header passthrough isn't working correctly in the LinuxServer.io FreshRSS image.
## Solution: Try Reeder Now Anyway
Even though the compatibility check fails, **Reeder might still work**. The check uses a different method than actual client authentication.
### Test in Reeder:
1. **Delete** existing FreshRSS account in Reeder
2. **Add New Account** → FreshRSS or Self-hosted
3. Enter:
- Server: `https://feeds.fig.systems`
- Username: `eddie`
- Password: `[YOUR API PASSWORD FROM WEB INTERFACE]`
4. **Try to sync**
The password should be the one you typed into the "API password" field in FreshRSS Profile settings.
## Alternative: Use Fever API Instead
Fever API uses different authentication and might work better.
### Your Fever Settings:
**Fever API URL:** `https://feeds.fig.systems/api/fever.php`
**Fever Key:** `b82fc4a3c3ff610ff270798ef6f93b13`
### In Reeder:
1. **Add Account** → **Fever**
2. Server: `https://feeds.fig.systems/api/fever.php`
3. Email: `eddie`
4. Password: `[YOUR WEB PASSWORD]` ← Uses web password, NOT API password!
Fever API doesn't require the Authorization header in the same way, so it might bypass this nginx issue.
## If Both Fail: Advanced Fix Required
If neither Google Reader API nor Fever API works, we need to:
1. **Switch to official FreshRSS Docker image** (not LinuxServer.io)
- Official image: `freshrss/freshrss:latest`
- Has proper nginx config out of the box
2. **Or: Use Apache instead of nginx** in LinuxServer image
- LinuxServer allows switching web servers
- Apache handles Authorization headers differently
3. **Or: Check Traefik logs** to see if header is being stripped there
```bash
docker logs traefik | grep -i authorization
```
## Recommended Action Plan
1. **TRY REEDER NOW** - might work despite compatibility check failure
2. **TRY FEVER API** - different auth method
3. **If both fail:** Check logs while attempting:
```bash
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/nginx/access.log
```
Look for the API requests and their response codes
## Debug Commands
### Check what Reeder sends:
```bash
# Watch access log while connecting from Reeder
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/nginx/access.log
```
### Test API manually:
```bash
# Replace with your actual API password
curl -v -d "Email=eddie" -d "Passwd=YOUR_API_PASSWORD" \
"https://feeds.fig.systems/api/greader.php/accounts/ClientLogin"
```
### Test Fever API:
```bash
curl -v -d "api_key=b82fc4a3c3ff610ff270798ef6f93b13" \
"https://feeds.fig.systems/api/fever.php?api"
```
## Sources & References
- [FreshRSS Authorization Header Issue #2308](https://github.com/FreshRSS/FreshRSS/issues/2308)
- [FreshRSS Apache/Nginx Configuration](https://freshrss.github.io/FreshRSS/en/admins/10_ServerConfig.html)
- [FreshRSS Mobile Access Guide](https://freshrss.github.io/FreshRSS/en/users/06_Mobile_access.html)
- [Nginx API 401 Discussion #6183](https://github.com/FreshRSS/FreshRSS/discussions/6183)
---
**Bottom Line:** Try Reeder with the API password now. If it doesn't work, try Fever API. Both might work even though the compatibility check fails.

239
compose/services/FreshRSS/DEBUG-LOGGING.md Normal file
View file

@ -0,0 +1,239 @@
# FreshRSS Debug Logging - Auth Troubleshooting
Debug logging has been enabled for FreshRSS to help troubleshoot authentication failures.
## What Was Changed
### 1. Environment Mode
Changed from `production` to `development`:
- File: `config/www/freshrss/data/config.php`
- Line 3: `'environment' => 'development'`
### 2. PHP Error Logging
Enabled verbose PHP error logging:
- File: `config/php/php-local.ini`
- Added:
```ini
error_reporting = E_ALL
display_errors = On
display_startup_errors = On
log_errors = On
error_log = /config/log/php_errors.log
```
### 3. Environment Variable
Added to `.env`:
```bash
FRESHRSS_ENV=development
```
## Where to Find Logs
### 1. PHP Error Log
**Location:** `/home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/php_errors.log`
View in real-time:
```bash
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/php_errors.log
```
### 2. FreshRSS Application Logs
**Location:** `/home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/`
List all logs:
```bash
ls -lah /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/
```
View recent logs:
```bash
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/*.log
```
### 3. Docker Container Logs
View container output:
```bash
docker logs freshrss -f
```
Last 100 lines:
```bash
docker logs freshrss --tail 100
```
### 4. Nginx Access/Error Logs
**Location:** `/home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/nginx/`
```bash
# Access log (HTTP requests)
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/nginx/nginx-access.log
# Error log
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/nginx/nginx-error.log
```
## Reproduce Auth Failure & Check Logs
### Step 1: Trigger the Auth Issue
1. Go to https://feeds.fig.systems
2. Attempt login or whatever triggers the auth failure
### Step 2: Check Logs Immediately
**Quick check all logs:**
```bash
cd /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log
tail -100 *.log
```
**Check PHP errors specifically:**
```bash
tail -50 /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/php_errors.log
```
**Search for authentication-related errors:**
```bash
cd /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log
grep -i "auth\|login\|session\|cookie\|permission\|denied" *.log | tail -20
```
### Step 3: Check SSO/Tinyauth Headers
Since you have `tinyauth` middleware enabled, check if headers are being passed correctly:
**View headers in browser:**
1. Open browser DevTools (F12)
2. Go to Network tab
3. Try to access FreshRSS
4. Click on the request
5. Check "Request Headers" for:
- `Remote-User`
- `Remote-Email`
- `Remote-Name`
- `Remote-Groups`
**Check Traefik logs:**
```bash
docker logs traefik | grep -i freshrss | tail -20
```
## Common Auth Issues & Log Indicators
### Issue: Tinyauth Header Not Being Passed
**Look for in logs:**
```
No authenticated user found
Missing Remote-User header
```
**Solution:** Check Traefik middleware configuration
### Issue: Session Cookie Issues
**Look for in logs:**
```
session_start(): Failed
Cannot send session cookie
Headers already sent
```
**Possible causes:**
- Cookie domain mismatch
- Secure cookie flag with HTTP
- SameSite cookie attribute
### Issue: Database Permission Errors
**Look for in logs:**
```
SQLITE: attempt to write a readonly database
Permission denied
```
**Solution:**
```bash
# Check file permissions
ls -la /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/www/freshrss/data/
# Fix if needed
sudo chown -R 1000:1000 /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/
```
### Issue: PHP Fatal Errors
**Look for in logs:**
```
Fatal error:
PHP Parse error:
Call to undefined function
```
## View Logs via Dozzle
Easiest way to view logs in real-time:
1. Go to https://logs-docker.fig.systems (from local network)
2. Click on **freshrss** container
3. Search for: `error`, `auth`, `login`, `fail`
4. Watch live as you reproduce the issue
## Disable Debug Logging (When Done)
Once you've identified the issue:
### 1. Revert Environment Mode
Edit: `config/www/freshrss/data/config.php`
```php
'environment' => 'production',
```
### 2. Disable PHP Error Display
Edit: `config/php/php-local.ini`
```ini
; Comment out or change:
display_errors = Off
display_startup_errors = Off
; Keep error logging:
log_errors = On
error_log = /config/log/php_errors.log
```
### 3. Restart FreshRSS
```bash
docker compose restart
```
## Example: Full Debug Session
```bash
# Terminal 1: Watch PHP errors
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/php_errors.log
# Terminal 2: Watch container logs
docker logs freshrss -f
# Terminal 3: Watch nginx access
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/nginx/nginx-access.log
# Now trigger the auth issue in browser and watch all 3 terminals
```
## Need More Verbose Logging?
Edit `config/www/freshrss/data/config.php` and enable additional debugging:
```php
'simplepie_syslog_enabled' => true, // Already enabled (line 24)
```
Check syslog:
```bash
docker exec freshrss cat /var/log/syslog | grep -i fresh
```
---
**Current Status:** ✅ Debug logging enabled and active
**Restart Required:** Already restarted
**Log Locations:** See "Where to Find Logs" section above

237
compose/services/FreshRSS/REEDER-AUTH-DEBUG.md Normal file
View file

@ -0,0 +1,237 @@
# Reeder Authentication Failure - Troubleshooting
## Current Status
✅ API enabled in FreshRSS
✅ API password hash exists for user 'eddie'
✅ Tinyauth SSO removed
❌ Reeder getting 401 Unauthorized
## Log Analysis
```
POST /api/greader.php/accounts/ClientLogin HTTP/1.1" 401
```
This means:
- Reeder is correctly hitting the Google Reader API endpoint
- Authentication is failing (401 = Unauthorized)
- Either wrong password OR the API password hasn't been properly set
## The Issue: API Password vs Web Password
FreshRSS has TWO different passwords:
1. **Web Password** - For logging into https://feeds.fig.systems
2. **API Password** - For iOS apps (Reeder, NetNewsWire, etc.)
**You MUST use the API password in Reeder, not your web password!**
## Step-by-Step Fix
### 1. Generate/Regenerate API Password
**Via Web Interface (Easiest):**
1. Go to https://feeds.fig.systems
2. Log in with your **web password**
3. Click your username (top right) → **Configuration**
4. Click **Profile** tab
5. Scroll down to **"API management"** or **"API"** section
6. Look for **"API password"** field
7. Click **"Generate"** or **"Regenerate"** button
8. **Write down the password immediately** - it won't be shown again!
The password will look something like: `aB3xK9mP2wQz7nYv`
### 2. Configure Reeder
Open Reeder on your iOS device:
1. **Add Account** → Select **FreshRSS** or **Self-hosted**
2. Enter these details:
- **Server:** `https://feeds.fig.systems`
- **Username:** `eddie`
- **Password:** `[THE API PASSWORD FROM STEP 1]` ← NOT your web password!
### 3. Test Authentication
Try to sync in Reeder. If it still fails, continue to advanced troubleshooting below.
## Advanced Troubleshooting
### Test API Manually
Run this test script:
```bash
/tmp/test-freshrss-api.sh
```
Or manually:
```bash
# Replace YOUR_API_PASSWORD with the actual API password
curl -v -d "Email=eddie" -d "Passwd=YOUR_API_PASSWORD" \
"https://feeds.fig.systems/api/greader.php/accounts/ClientLogin"
# Should return 200 and an auth token, NOT 401
```
### Check What Reeder is Sending
Watch the logs while you try to connect from Reeder:
```bash
tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/nginx/access.log
```
Look for:
- Is username being sent correctly? (should be 'eddie')
- Multiple 401s = wrong password
- 404 = wrong URL endpoint
### Common Issues
#### Issue 1: Using Web Password Instead of API Password
**Symptom:** 401 errors
**Solution:** Generate API password in web interface, use THAT password
#### Issue 2: API Password Never Generated
**Symptom:** 401 errors
**Check:** Look in web interface - is the API password field empty?
**Solution:** Click "Generate" to create one
#### Issue 3: Wrong Username
**Symptom:** 401 errors
**Check:** Username must be exactly `eddie` (the FreshRSS username)
**Solution:** Double-check spelling and case
#### Issue 4: Wrong Server URL
**Symptom:** Connection errors or 404
**Check:** Must be `https://feeds.fig.systems` (no trailing slash)
**Solution:** Remove any extra characters
#### Issue 5: Reeder Using Wrong API Type
**Symptom:** 404 or unexpected responses
**Solution:** In Reeder, make sure you selected:
- "FreshRSS" account type (if available)
- OR "Self-hosted" → "Google Reader API"
- NOT "Fever API" (different authentication)
## Verify API is Actually Working
### Method 1: Use Fever API Instead
FreshRSS also supports Fever API. Your Fever key is:
```
b82fc4a3c3ff610ff270798ef6f93b13
```
Try in Reeder:
1. **Add Account** → **Fever**
2. **Server:** `https://feeds.fig.systems/api/fever.php`
3. **Email:** `eddie`
4. **Password:** Your **web password** (Fever uses web password, not API password!)
If Fever works but Google Reader API doesn't, there's an issue with the Google Reader API specifically.
### Method 2: Check from Another Device
Try accessing from desktop:
```bash
curl -d "Email=eddie" -d "Passwd=YOUR_API_PASSWORD" \
"https://feeds.fig.systems/api/greader.php/accounts/ClientLogin"
```
If this returns a token, the API works and the issue is Reeder-specific.
## Reset Everything
If nothing works, reset the API authentication:
### 1. Clear API Password
```bash
# Backup first
cp /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/www/freshrss/data/users/eddie/config.php \
/home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/www/freshrss/data/users/eddie/config.php.backup
# Edit the config file manually to clear API password
# Look for 'apiPasswordHash' and set it to empty string
```
### 2. Regenerate via Web Interface
1. Log into https://feeds.fig.systems
2. Go to Profile → API management
3. Generate NEW API password
4. Try again in Reeder
## Check FreshRSS Version
```bash
docker exec freshrss cat /app/freshrss/constants.php | grep FRESHRSS_VERSION
```
If it's very old, some API features might not work correctly.
Update:
```bash
cd /home/eduardo_figueroa/homelab/compose/services/FreshRSS
docker compose pull
docker compose up -d
```
## Enable More Verbose API Logging
Edit: `/home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/www/freshrss/data/config.php`
Add:
```php
'simplepie_syslog_enabled' => true,
```
Then check syslog:
```bash
docker exec freshrss cat /var/log/syslog 2>/dev/null | grep -i "api\|auth\|greader"
```
## Still Not Working?
### Nuclear Option: Recreate User
If API auth is completely broken for this user:
1. **Export your feeds** (Settings → Import/Export)
2. **Create NEW user** in FreshRSS web interface
3. **Generate API password** for new user
4. **Import feeds** to new user
5. **Try Reeder** with new user credentials
## Test Results Template
When asking for help, provide:
```
Username: eddie
Server URL: https://feeds.fig.systems
Reeder Account Type: [FreshRSS / Self-hosted / Other]
API Password Generated: [Yes / No]
Using API Password (not web password): [Yes / No]
curl test result:
[paste output of test script]
Recent nginx logs:
[paste last 5 lines from access.log during attempt]
```
---
**Most Common Solution:** You need to generate a NEW API password in the web interface and use THAT specific password in Reeder, not your web login password.