From a0ff5adda8214d477bce8a0c903614b7c6693a98 Mon Sep 17 00:00:00 2001
From: hobokenchicken <dustin@dustin.coffee>
Date: Tue, 14 Apr 2026 13:42:35 -0400
Subject: [PATCH] docs: add troubleshooting guide

Document common issues and solutions including:
- NPM deprecation warnings (safe to ignore)
- Database connection issues
- Webhook configuration
- SSL certificate problems
- Memory and performance tuning
---
 docs/TROUBLESHOOTING.md | 194 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 194 insertions(+)
 create mode 100644 docs/TROUBLESHOOTING.md

diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
new file mode 100644
index 0000000..8afe811
--- /dev/null
+++ b/docs/TROUBLESHOOTING.md
@@ -0,0 +1,194 @@
+# CoopCredits Troubleshooting Guide
+
+## Installation Warnings
+
+### NPM Deprecation Warnings
+
+When running `npm install`, you may see warnings like:
+
+```
+npm WARN deprecated inflight@1.0.6: This module is not supported...
+npm WARN deprecated glob@7.2.0: Old versions of glob are not supported...
+npm WARN deprecated @walletconnect/sign-client@2.19.0: ...
+```
+
+**These are safe to ignore.** These warnings come from:
+- Transitive dependencies (dependencies of dependencies)
+- Solana wallet adapter packages that haven't updated yet
+- Legacy packages still used by the Anchor framework
+
+**Critical fix applied:**
+- ✅ Next.js updated from 14.0.4 to 14.2.15 (security vulnerability patched)
+
+**What you can do:**
+```bash
+# The warnings don't affect functionality
+# To suppress them during install:
+npm install --silent
+
+# Or use --legacy-peer-deps if needed:
+npm install --legacy-peer-deps
+```
+
+## Common Issues
+
+### Database Connection Failed
+
+**Error:** `Can't reach database server at localhost:5432`
+
+**Solution:**
+```bash
+# Start PostgreSQL
+docker-compose up -d postgres
+
+# Wait for it to be ready
+sleep 5
+
+# Verify
+docker-compose exec postgres pg_isready -U coop
+```
+
+### Solana Program Build Fails
+
+**Error:** `anchor build` fails with Rust errors
+
+**Solution:**
+```bash
+# Update Rust
+cd anchor-program
+rustup update
+
+# Rebuild
+anchor clean
+anchor build
+```
+
+### Webhooks Not Receiving
+
+**Error:** Tautulli/Overseer webhooks not triggering
+
+**Solution:**
+1. Verify CoopCredits backend is accessible:
+   ```bash
+   curl https://coop.hobokenchicken.com/health
+   ```
+
+2. Check webhook URL in Tautulli/Overseer settings
+
+3. Check Nginx logs:
+   ```bash
+   tail -f docker/nginx/logs/access.log
+   ```
+
+4. Test webhook manually:
+   ```bash
+   curl -X POST https://coop.hobokenchicken.com/webhooks/tautulli \
+     -H "Content-Type: application/json" \
+     -d '{"test": true}'
+   ```
+
+### Cannot Reach Local Services (172.20.1.x)
+
+**Error:** Backend cannot connect to Plex/Tautulli/Overseer
+
+**Solution:**
+```bash
+# Test connectivity from backend container
+docker exec coop-backend ping 172.20.1.255
+
+# Check Docker network
+docker network ls
+docker network inspect coop-credits_coop-external
+
+# Verify firewall rules
+sudo ufw status
+```
+
+### Wallet Creation Fails
+
+**Error:** `Failed to create wallet` or Solana errors
+
+**Solution:**
+```bash
+# Check Solana configuration
+solana config get
+
+# Ensure you're on devnet
+solana config set --url devnet
+
+# Check balance
+solana balance
+
+# Request airdrop if needed
+solana airdrop 2
+```
+
+### SSL Certificate Errors
+
+**Error:** Browser shows certificate warnings
+
+**Solution:**
+```bash
+# Check certificate
+openssl s_client -connect coop.hobokenchicken.com:443
+
+# Renew Let's Encrypt
+docker-compose -f docker-compose.prod.yml run --rm certbot renew
+
+# Or use self-signed for testing:
+openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+  -keyout docker/nginx/ssl/key.pem \
+  -out docker/nginx/ssl/cert.pem \
+  -subj '/CN=coop.hobokenchicken.com'
+```
+
+### CORS Errors in Browser
+
+**Error:** `Access-Control-Allow-Origin` errors
+
+**Solution:**
+1. Check `FRONTEND_URL` in backend `.env` matches your actual URL
+2. Verify CORS_ORIGINS includes your domain
+3. Restart backend after changes
+
+### High Memory Usage
+
+**Symptom:** Server slows down or OOM errors
+
+**Solution:**
+```bash
+# Check what's using memory
+docker stats
+
+# Restart services
+docker-compose -f docker-compose.prod.yml restart
+
+# Increase swap if needed
+sudo fallocate -l 2G /swapfile
+sudo chmod 600 /swapfile
+sudo mkswap /swapfile
+sudo swapon /swapfile
+```
+
+## Getting Help
+
+1. Check health status:
+   ```bash
+   ./deployment/health-check.sh
+   ```
+
+2. View all logs:
+   ```bash
+   docker-compose -f docker-compose.prod.yml logs -f
+   ```
+
+3. Check specific service:
+   ```bash
+   docker-compose -f docker-compose.prod.yml logs -f backend
+   ```
+
+4. Verify environment:
+   ```bash
+   # Check all required env vars are set
+grep -E '^\w+=' .env | wc -l
+   ```