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