homelab/compose/services/FreshRSS/DEBUG-LOGGING.md

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:

  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:

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:

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:

ls -lah /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/

View recent logs:

tail -f /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/*.log

3. Docker Container Logs

View container output:

docker logs freshrss -f

Last 100 lines:

docker logs freshrss --tail 100

4. Nginx Access/Error Logs

Location: /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/nginx/

# 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:

cd /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log
tail -100 *.log

Check PHP errors specifically:

tail -50 /home/eduardo_figueroa/homelab/compose/services/FreshRSS/config/log/php_errors.log

Search for authentication-related errors:

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:

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:

# 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

'environment' => 'production',

2. Disable PHP Error Display

Edit: config/php/php-local.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

docker compose restart

Example: Full Debug Session

# 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:

'simplepie_syslog_enabled' => true,  // Already enabled (line 24)

Check syslog:

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