fx-test/fluxer-seattle/README.md

# 🌊 Fluxer Seattle Deployment

> **Seattle-themed Fluxer deployment with human verification fixes for st.vish.gg**

This deployment contains all the fixes and configurations needed to run Fluxer without human verification issues, optimized for public access with friends.

## 🚀 Quick Start

### One-liner Complete Setup
```bash
curl -sSL https://git.vish.gg/Vish/homelab/raw/branch/main/deployments/fluxer-seattle/complete-setup.sh | bash
```

### One-liner Fix Only (for existing installations)
```bash
curl -sSL https://git.vish.gg/Vish/homelab/raw/branch/main/deployments/fluxer-seattle/fix-human-verification.sh | bash
```

## 📁 Files Included

### 🔧 Setup Scripts
- **`complete-setup.sh`** - Full Fluxer installation with all fixes applied
- **`fix-human-verification.sh`** - Apply fixes to existing Fluxer installation

### ⚙️ Configuration Files
- **`AuthRateLimitConfig.ts`** - Updated rate limiting (50 requests/60 seconds)

### 📚 Documentation
- **`BRANCH_MANAGEMENT.md`** - Guide for managing development branches
- **`README.md`** - This file

## 🛠️ What These Fixes Do

### 1. **Rate Limit Fixes**
- Increases registration rate limits from 10/10sec to 50/60sec
- Prevents "too many requests" errors during friend signups
- Clears Redis cache to reset existing rate limit counters

### 2. **Human Verification Bypass**
- Disables manual review system that blocks new registrations
- Removes verification requirements for public access
- Allows immediate account activation

### 3. **Database Cleanup**
- Clears stuck accounts from verification queues
- Resets user states that prevent login
- Fixes existing accounts that got stuck in verification

## 🏗️ Architecture

```
st.vish.gg (Fluxer Instance)
├── API Service (fluxer_api)
│   ├── Rate Limiting ✅ Fixed
│   ├── Auth System ✅ Bypassed
│   └── Manual Review ✅ Disabled
├── Database (PostgreSQL)
│   ├── User States ✅ Cleaned
│   └── Verification Queue ✅ Cleared
└── Cache (Redis)
    └── Rate Limits ✅ Reset
```

## 🔄 Deployment Process

### From Scratch
1. **Clone Repository**: Gets latest Fluxer code
2. **Apply Fixes**: Modifies configuration files
3. **Setup Database**: Configures PostgreSQL with proper settings
4. **Clear Caches**: Resets Redis and clears stuck states
5. **Start Services**: Launches all Fluxer components
6. **Verify Setup**: Tests registration and login flows

### Existing Installation
1. **Backup Current State**: Saves existing configuration
2. **Apply Configuration Changes**: Updates rate limits and auth settings
3. **Clear Stuck Data**: Removes verification blocks
4. **Restart Services**: Applies changes
5. **Test Functionality**: Verifies fixes work

## 🌐 Public Access Configuration

### Domain Setup
- **Primary**: `st.vish.gg`
- **SSL**: Automatic via Cloudflare
- **CDN**: Cloudflare proxy enabled

### Security Settings
- **Rate Limiting**: Generous but not unlimited (50/60sec)
- **Registration**: Open to public
- **Verification**: Disabled for immediate access
- **Manual Review**: Bypassed

## 🔍 Troubleshooting

### Common Issues

#### "Too Many Requests" Error
```bash
# Clear Redis cache
docker exec fluxer_redis redis-cli FLUSHALL
# Restart API service
docker restart fluxer_api
```

#### Users Stuck in Verification
```bash
# Run the fix script
curl -sSL https://git.vish.gg/Vish/homelab/raw/branch/main/deployments/fluxer-seattle/fix-human-verification.sh | bash
```

#### Service Won't Start
```bash
# Check logs
docker logs fluxer_api
docker logs fluxer_gateway
# Restart all services
docker-compose restart
```

## 📊 Monitoring

### Health Checks
- **API Health**: `https://st.vish.gg/api/health`
- **Gateway Status**: `https://st.vish.gg/gateway/health`
- **Database Connection**: Check via API logs

### Key Metrics
- **Registration Success Rate**: Should be >95%
- **Login Success Rate**: Should be >98%
- **API Response Time**: Should be <500ms
- **Error Rate**: Should be <1%

## 🛡️ Admin Panel Setup

### Overview
Fluxer has an admin panel at `https://st.vish.gg/admin` using its own OAuth2 login.

### Required Configuration (in `dev/.env`)
```
ADMIN_OAUTH2_CLIENT_ID=<app id from secret.txt>
ADMIN_OAUTH2_CLIENT_SECRET=<secret from secret.txt>
FLUXER_PATH_ADMIN=/
FLUXER_ADMIN_ENDPOINT=https://st.vish.gg/admin
```

**Important**: Set `FLUXER_PATH_ADMIN=/` (not `/admin`) because Caddy already strips the `/admin` prefix before forwarding to the admin container.

### Grant Admin Access (Cassandra)
Replace `<YOUR_USER_ID>` with the numeric user ID from Cassandra:
```bash
docker exec dev-cassandra-1 cqlsh -e \
  "UPDATE fluxer.users SET acls = {'*'} WHERE user_id = <YOUR_USER_ID>;"
```

### Fix: Admin API Routing (compose.yaml)
The admin container must call the API via the internal Docker network, not the external Cloudflare URL, to avoid intermittent timeouts causing 403 errors on `/storage` and other metrics pages.

In `dev/compose.yaml`, under the `admin` service's `environment`, add:
```yaml
- FLUXER_API_PUBLIC_ENDPOINT=http://api:8080
```

### Known Issues
- **"Forbidden: requires metrics:view permission"** on storage/jobs/metrics pages: caused by the admin calling the API through the external HTTPS URL (with Cloudflare latency). Fixed by the `FLUXER_API_PUBLIC_ENDPOINT=http://api:8080` override above.
- **"You find yourself in a strange place"** after login: user account has no admin ACLs. Fix with the Cassandra UPDATE above.
- **Double `/admin/admin/dashboard`** redirect: `FLUXER_PATH_ADMIN` was set to `/admin` instead of `/`.
- **Stale build cache**: if admin behaves unexpectedly after config changes, run:
  ```bash
  docker volume rm dev_admin_build
  docker compose -f dev/compose.yaml up -d admin
  ```

## 🔐 Security Considerations

### What's Disabled
- ❌ Manual review system
- ❌ Phone verification requirements
- ❌ Email verification for immediate access
- ❌ Strict rate limiting

### What's Still Protected
- ✅ Password requirements
- ✅ Basic spam protection
- ✅ SQL injection prevention
- ✅ XSS protection
- ✅ CSRF tokens

## 🚀 Future Updates

### Updating Fixes
```bash
cd /path/to/homelab
git pull origin main
# Re-run setup if needed
curl -sSL https://git.vish.gg/Vish/homelab/raw/branch/main/deployments/fluxer-seattle/complete-setup.sh | bash
```

### Monitoring for Issues
- Watch registration success rates
- Monitor API error logs
- Check for new verification requirements in Fluxer updates

## 📞 Support

### Quick Fixes
1. **Registration Issues**: Run `fix-human-verification.sh`
2. **Rate Limit Issues**: Clear Redis cache
3. **Service Issues**: Check Docker logs and restart

### Getting Help
- Check the troubleshooting section above
- Review Docker logs for specific errors
- Test with the health check endpoints

---

**🌊 Fluxer Seattle - Making Discord alternatives accessible for everyone!**