docs: update all documentation to reflect current project state
This commit is contained in:
+80
-132
@@ -1,35 +1,5 @@
|
||||
# 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
|
||||
@@ -48,21 +18,6 @@ sleep 5
|
||||
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
|
||||
@@ -75,16 +30,18 @@ anchor build
|
||||
|
||||
2. Check webhook URL in Tautulli/Overseer settings
|
||||
|
||||
3. Check Nginx logs:
|
||||
3. Check Caddy routes `/webhooks/*` to backend port 3002
|
||||
|
||||
4. Check backend logs:
|
||||
```bash
|
||||
tail -f docker/nginx/logs/access.log
|
||||
docker logs --tail 50 coop-backend
|
||||
```
|
||||
|
||||
4. Test webhook manually:
|
||||
5. Test webhook manually:
|
||||
```bash
|
||||
curl -X POST https://coop.hobokenchicken.com/webhooks/tautulli \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"test": true}'
|
||||
-d '{"action":"watched","user_id":"1","rating_key":"1","session_key":"1","media_type":"movie","title":"Test","started":1,"stopped":3601,"percent_complete":90}'
|
||||
```
|
||||
|
||||
### Cannot Reach Local Services (172.20.1.x)
|
||||
@@ -93,85 +50,72 @@ anchor build
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Test connectivity from backend container
|
||||
docker exec coop-backend ping 172.20.1.255
|
||||
# Verify backend is in host network mode
|
||||
docker inspect coop-backend | grep NetworkMode
|
||||
# Should show: "host"
|
||||
|
||||
# Check Docker network
|
||||
docker network ls
|
||||
docker network inspect coop-credits_coop-external
|
||||
# Test connectivity from host
|
||||
ping 172.20.1.255
|
||||
|
||||
# Verify firewall rules
|
||||
sudo ufw status
|
||||
# Check backend logs
|
||||
docker logs --tail 50 coop-backend
|
||||
|
||||
# Verify env vars
|
||||
docker exec coop-backend env | grep TAUTULLI
|
||||
docker exec coop-backend env | grep OVERSEER
|
||||
```
|
||||
|
||||
### Wallet Creation Fails
|
||||
> Backend must use `network_mode: host` to reach `172.20.1.x` subnet. Docker bridge networking cannot route to this subnet.
|
||||
|
||||
**Error:** `Failed to create wallet` or Solana errors
|
||||
### Ko-fi Webhook Not Working
|
||||
|
||||
**Error:** Payments not crediting users
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Check Solana configuration
|
||||
solana config get
|
||||
1. Verify `KOFI_VERIFICATION_TOKEN` env var is set in backend container:
|
||||
```bash
|
||||
docker exec coop-backend env | grep KOFI
|
||||
```
|
||||
|
||||
# Ensure you're on devnet
|
||||
solana config set --url devnet
|
||||
2. Check Ko-fi webhook settings — URL should be:
|
||||
```
|
||||
https://coop.hobokenchicken.com/webhooks/kofi
|
||||
```
|
||||
|
||||
# Check balance
|
||||
solana balance
|
||||
3. Check backend logs for verification token mismatch
|
||||
|
||||
# Request airdrop if needed
|
||||
solana airdrop 2
|
||||
4. Check admin **Donations** tab to see if payments arrive as UNCLAIMED (email mismatch)
|
||||
|
||||
### BigInt JSON Serialization Error
|
||||
|
||||
**Error:** `Do not know how to serialize a BigInt`
|
||||
|
||||
**Solution:** This is fixed in `backend/src/index.ts` with:
|
||||
```typescript
|
||||
(BigInt.prototype as any).toJSON = function () {
|
||||
return this.toString();
|
||||
};
|
||||
```
|
||||
|
||||
If you still see it, ensure the patch is loaded before any route handlers.
|
||||
|
||||
### 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
|
||||
2. Verify CORS origins include your domain in `backend/src/index.ts`
|
||||
3. Restart backend after changes
|
||||
|
||||
### High Memory Usage
|
||||
### Rate Limiting (429 Too Many Requests)
|
||||
|
||||
**Symptom:** Server slows down or OOM errors
|
||||
**Error:** Dashboard shows "Slow down, chicken!" or fails to load
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
## Docker Build Issues
|
||||
|
||||
### Backend Build Fails: Cannot redeclare block-scoped variable
|
||||
|
||||
**Error:** `error TS2451: Cannot redeclare block-scoped variable 'signature'`
|
||||
|
||||
**Solution:** Fixed in source. If you see this, pull the latest code.
|
||||
|
||||
### Backend: Prisma Client could not locate Query Engine
|
||||
|
||||
**Error:** `PrismaClientInitializationError: Prisma Client could not locate the Query Engine`
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Regenerate Prisma client with correct binary target
|
||||
cd backend
|
||||
npx prisma generate
|
||||
|
||||
# Rebuild backend container
|
||||
docker-compose up -d --build backend
|
||||
```
|
||||
- Rate limit is 1000 requests per 15 minutes per IP
|
||||
- If you hit it, wait a few minutes
|
||||
- The dashboard makes several parallel calls on load — this is normal
|
||||
|
||||
### Frontend Build Fails: Module not found
|
||||
|
||||
@@ -184,23 +128,7 @@ docker-compose up -d --build backend
|
||||
}
|
||||
```
|
||||
|
||||
### Frontend: Prerender Error on /login
|
||||
|
||||
**Error:** `Error occurred prerendering page "/login"`
|
||||
|
||||
**Solution:** This was caused by zustand persist middleware accessing localStorage during SSR. Fixed by wrapping providers with dynamic import `ssr: false`.
|
||||
|
||||
### Frontend: Cannot find module 'next-themes'
|
||||
|
||||
**Error:** `Module not found: Can't resolve 'next-themes'`
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
cd frontend
|
||||
npm install next-themes
|
||||
```
|
||||
|
||||
### Docker Compose: Public Directory Not Found
|
||||
### Docker Build: Public Directory Not Found
|
||||
|
||||
**Error:** `failed to calculate checksum: "/app/frontend/public": not found`
|
||||
|
||||
@@ -210,25 +138,45 @@ mkdir -p frontend/public
|
||||
touch frontend/public/.gitkeep
|
||||
```
|
||||
|
||||
### Request Stuck on PENDING
|
||||
|
||||
**Error:** Request never updates from PENDING status
|
||||
|
||||
**Solution:**
|
||||
1. Check Overseer webhook is configured correctly
|
||||
2. In admin dashboard, go to **The Feed Queue** tab and click **SYNC**
|
||||
3. Or manually sync from dashboard's Requests tab
|
||||
4. Check backend logs for Overseer API errors
|
||||
|
||||
### Disk Space Not Updating
|
||||
|
||||
**Error:** Silo bar shows old values after downloading large files
|
||||
|
||||
**Solution:**
|
||||
- Disk space is cached for 30 seconds
|
||||
- Wait 30 seconds and refresh
|
||||
- The bar updates automatically on dashboard load
|
||||
|
||||
## Getting Help
|
||||
|
||||
1. Check health status:
|
||||
1. View all logs:
|
||||
```bash
|
||||
./deployment/health-check.sh
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
2. View all logs:
|
||||
2. Check specific service:
|
||||
```bash
|
||||
docker-compose -f docker-compose.prod.yml logs -f
|
||||
docker-compose logs -f backend
|
||||
docker-compose logs -f frontend
|
||||
```
|
||||
|
||||
3. Check specific service:
|
||||
```bash
|
||||
docker-compose -f docker-compose.prod.yml logs -f backend
|
||||
```
|
||||
|
||||
4. Verify environment:
|
||||
3. Verify environment:
|
||||
```bash
|
||||
# Check all required env vars are set
|
||||
grep -E '^\w+=' .env | wc -l
|
||||
```
|
||||
|
||||
4. Check database:
|
||||
```bash
|
||||
docker exec coop-postgres psql -U coop -d coop_credits -c "SELECT COUNT(*) FROM users;"
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user