Sanitized mirror from private repository - 2026-03-31 10:10:42 UTC

2026-03-31 10:10:43 +00:00
commit 29e47b18e9
1283 changed files with 331758 additions and 0 deletions
--- a/docs/admin/AGENTS.md
+++ b/docs/admin/AGENTS.md
@@ -0,0 +1,332 @@
+# Homelab Repository Knowledge
+
+**Repository**: Vish's Homelab Infrastructure  
+**Location**: /root/homelab  
+**Primary Domain**: vish.gg  
+**Status**: Multi-server production deployment
+
+## 🏠 Homelab Overview
+
+This repository manages a comprehensive homelab infrastructure including:
+- **Gaming servers** (Minecraft, Garry's Mod via PufferPanel)
+- **Fluxer Chat** (self-hosted messaging platform at st.vish.gg - replaced Stoatchat)
+- **Media services** (Plex, Jellyfin, *arr stack)
+- **Development tools** (Gitea, CI/CD, monitoring)
+- **Security hardening** and monitoring
+
+## 🎮 Gaming Server (VPS)
+
+**Provider**: Contabo VPS  
+**Specs**: 8 vCPU, 32GB RAM, 400GB NVMe  
+**Location**: /root/homelab (this server)  
+**Access**: SSH on ports 22 (primary) and 2222 (backup)
+
+### Recent Security Hardening (February 2026)
+- ✅ SSH hardened with key-only authentication
+- ✅ Backup SSH access on port 2222 (IP restricted)
+- ✅ Fail2ban configured for intrusion prevention
+- ✅ UFW firewall with rate limiting
+- ✅ Emergency access management tools created
+
+## 🛡️ Security Infrastructure
+
+### SSH Configuration
+- **Primary SSH**: Port 22 (Tailscale + direct IP)
+- **Backup SSH**: Port 2222 (restricted to IP YOUR_WAN_IP)
+- **Authentication**: SSH keys only, passwords disabled
+- **Protection**: Fail2ban monitoring both ports
+
+### Management Scripts
+```bash
+# Security status check
+/root/scripts/security-check.sh
+
+# Backup access management
+/root/scripts/backup-access-manager.sh [enable|disable|status]
+
+# Service management
+./manage-services.sh [start|stop|restart|status]
+```
+
+## 🌐 Fluxer Chat Service (st.vish.gg)
+
+**Repository**: Fluxer (Modern messaging platform)  
+**Location**: /root/fluxer  
+**Domain**: st.vish.gg  
+**Status**: Production deployment on this server (replaced Stoatchat on 2026-02-15)
+
+## 🏗️ Architecture Overview
+
+Fluxer is a modern self-hosted messaging platform with the following components:
+
+### Core Services
+- **Caddy**: Port 8088 - Frontend web server serving React app
+- **API**: Port 8080 (internal) - REST API backend with authentication
+- **Gateway**: WebSocket gateway for real-time communication
+- **Postgres**: Primary database for user data and messages
+- **Redis**: Caching and session storage
+- **Cassandra**: Message storage and history
+- **Minio**: S3-compatible file storage
+- **Meilisearch**: Search engine for messages and content
+
+### Supporting Services
+- **Worker**: Background job processing
+- **Media**: Media processing service
+- **ClamAV**: Antivirus scanning for uploads
+- **Metrics**: Monitoring and metrics collection
+- **LiveKit**: Voice/video calling (not configured)
+- **Nginx**: Ports 80/443 - Reverse proxy and SSL termination
+
+## 🔧 Key Commands
+
+### Service Management
+```bash
+# Start all services
+cd /root/fluxer && docker compose -f dev/compose.yaml up -d
+
+# Stop all services
+cd /root/fluxer && docker compose -f dev/compose.yaml down
+
+# View service status
+cd /root/fluxer && docker compose -f dev/compose.yaml ps
+
+# View logs for specific service
+cd /root/fluxer && docker compose -f dev/compose.yaml logs [service_name]
+
+# Restart specific service
+cd /root/fluxer && docker compose -f dev/compose.yaml restart [service_name]
+```
+
+### Development
+```bash
+# View all container logs
+cd /root/fluxer && docker compose -f dev/compose.yaml logs -f
+
+# Access API container shell
+cd /root/fluxer && docker compose -f dev/compose.yaml exec api bash
+
+# Check environment variables
+cd /root/fluxer && docker compose -f dev/compose.yaml exec api env
+```
+
+### Backup & Recovery
+```bash
+# Create backup
+./backup.sh
+
+# Restore from backup
+./restore.sh /path/to/backup/directory
+
+# Setup automated backups
+./setup-backup-cron.sh
+```
+
+## 📁 Important Files
+
+### Configuration
+- **Revolt.toml**: Base configuration
+- **Revolt.overrides.toml**: Environment-specific overrides (SMTP, domains, etc.)
+- **livekit.yml**: Voice/video service configuration
+
+### Scripts
+- **manage-services.sh**: Service management
+- **backup.sh**: Backup system
+- **restore.sh**: Restore system
+
+### Documentation
+- **SYSTEM_VERIFICATION.md**: Complete system status and verification
+- **OPERATIONAL_GUIDE.md**: Day-to-day operations and troubleshooting
+- **DEPLOYMENT_DOCUMENTATION.md**: Full deployment guide for new machines
+
+## 🌐 Domain Configuration
+
+### Production URLs
+- **Frontend**: https://st.vish.gg
+- **API**: https://api.st.vish.gg
+- **WebSocket**: https://events.st.vish.gg
+- **Files**: https://files.st.vish.gg
+- **Proxy**: https://proxy.st.vish.gg
+- **Voice**: https://voice.st.vish.gg
+
+### SSL Certificates
+- **Provider**: Let's Encrypt
+- **Location**: /etc/letsencrypt/live/st.vish.gg/
+- **Auto-renewal**: Configured via certbot
+
+## 📧 Email Configuration
+
+### SMTP Settings
+- **Provider**: Gmail SMTP
+- **Host**: smtp.gmail.com:465 (SSL)
+- **From**: your-email@example.com
+- **Authentication**: App Password
+- **Status**: Fully functional
+
+### Email Testing
+```bash
+# Test account creation (sends verification email)
+curl -X POST http://localhost:14702/auth/account/create \
+  -H "Content-Type: application/json" \
+  -d '{"email": "test@example.com", "password": "TestPass123!"}'
+```
+
+## 🔐 User Management
+
+### Account Operations
+```bash
+# Create account
+curl -X POST http://localhost:14702/auth/account/create \
+  -H "Content-Type: application/json" \
+  -d '{"email": "user@domain.com", "password": "SecurePass123!"}'
+
+# Login
+curl -X POST http://localhost:14702/auth/session/login \
+  -H "Content-Type: application/json" \
+  -d '{"email": "user@domain.com", "password": "SecurePass123!"}'
+```
+
+### Test Accounts
+- **user@example.com**: Verified test account (password: "REDACTED_PASSWORD"
+- **Helgrier**: user@example.com (password: "REDACTED_PASSWORD"
+
+## 🚨 Troubleshooting
+
+### Common Issues
+1. **Service won't start**: Check port availability, restart with manage-services.sh
+2. **Email not received**: Check spam folder, verify SMTP credentials in Revolt.overrides.toml
+3. **SSL issues**: Verify certificate renewal with `certbot certificates`
+4. **Frontend not loading**: Check nginx configuration and service status
+
+### Log Locations
+- **Services**: *.log files in /root/stoatchat/
+- **Nginx**: /var/log/nginx/error.log
+- **System**: /var/log/syslog
+
+### Health Checks
+```bash
+# Quick service check
+for port in 14702 14703 14704 14705 14706; do
+  echo "Port $port: $(curl -s -o /dev/null -w "%{http_code}" http://localhost:$port/)"
+done
+
+# API health
+curl -s http://localhost:14702/ | jq '.revolt'
+```
+
+## 💾 Backup Strategy
+
+### Automated Backups
+- **Schedule**: Daily at 2 AM via cron
+- **Location**: /root/stoatchat-backups/
+- **Retention**: Manual cleanup (consider implementing rotation)
+
+### Backup Contents
+- Configuration files (Revolt.toml, Revolt.overrides.toml)
+- SSL certificates
+- Nginx configuration
+- User uploads and file storage
+
+### Recovery Process
+1. Stop services: `./manage-services.sh stop`
+2. Restore: `./restore.sh /path/to/backup`
+3. Start services: `./manage-services.sh start`
+
+## 🔄 Deployment Process
+
+### For New Machines
+1. Follow DEPLOYMENT_DOCUMENTATION.md
+2. Update domain names in configurations
+3. Configure SMTP credentials
+4. Obtain SSL certificates
+5. Test all services
+
+### Updates
+1. Backup current system: `./backup.sh`
+2. Stop services: `./manage-services.sh stop`
+3. Pull updates: `git pull origin main`
+4. Rebuild: `cargo build --release`
+5. Start services: `./manage-services.sh start`
+
+## 📊 Monitoring
+
+### Performance Metrics
+- **CPU/Memory**: Monitor with `top -p $(pgrep -d',' revolt)`
+- **Disk Usage**: Check with `df -h` and `du -sh /root/stoatchat`
+- **Network**: Monitor connections with `netstat -an | grep -E "(14702|14703|14704|14705|14706)"`
+
+### Maintenance Schedule
+- **Daily**: Check service status, review error logs
+- **Weekly**: Run backups, check SSL certificates
+- **Monthly**: Update system packages, test backup restoration
+
+## 🎯 Current Status - FLUXER FULLY OPERATIONAL ✅
+
+**Last Updated**: February 15, 2026
+- ✅ **MIGRATION COMPLETE**: Stoatchat replaced with Fluxer messaging platform
+- ✅ All Fluxer services operational and accessible externally
+- ✅ SSL certificates valid (Let's Encrypt, expires May 12, 2026)
+- ✅ Frontend accessible at https://st.vish.gg
+- ✅ API endpoints responding correctly
+- ✅ **USER REGISTRATION WORKING**: Captcha issue resolved by disabling captcha verification
+- ✅ Test user account created successfully (ID: 1472533637105737729)
+- ✅ Complete documentation updated for Fluxer deployment
+- ✅ **DEPLOYMENT DOCUMENTED**: Full configuration saved in homelab repository
+
+### Complete Functionality Testing Results
+**Test Date**: February 11, 2026  
+**Test Status**: ✅ **ALL TESTS PASSED (6/6)**
+
+#### Test Account Created & Verified
+- **Email**: admin@example.com
+- **Account ID**: 01KH5RZXBHDX7W29XXFN6FB35F
+- **Status**: Verified and active
+- **Session Token**: Working (W_NfvzjWiukjVQEi30zNTmvPo4xo7pPJTKCZRvRP7TDQplfOjwgoad3AcuF9LEPI)
+
+#### Functionality Tests Completed
+1. ✅ **Account Creation**: HTTP 204 success via API
+2. ✅ **Email Verification**: Email delivered and verified successfully
+3. ✅ **Authentication**: Login successful, session token obtained
+4. ✅ **Web Interface**: Frontend accessible and functional
+5. ✅ **Real-time Messaging**: Message sent successfully in Nerds channel
+6. ✅ **Infrastructure**: All services responding correctly
+
+### Cloudflare Issue Resolution
+- **Solution**: Switched from Cloudflare proxy mode to DNS-only mode
+- **Result**: All services now accessible externally via direct SSL connections
+- **Status**: 100% operational - all domains working perfectly
+- **Verification**: All endpoints tested and confirmed working
+- **DNS Records**: All set to DNS-only (no proxy) pointing to YOUR_WAN_IP
+
+### Documentation Created
+- **DEPLOYMENT_DOCUMENTATION.md**: Complete deployment guide for new machines
+- **OPERATIONAL_STATUS.md**: Comprehensive testing results and operational status
+- **AGENTS.md**: Updated with final status and testing results (this file)
+
+## 📚 Additional Context
+
+### Technology Stack
+- **Language**: Rust
+- **Database**: Redis
+- **Web Server**: Nginx
+- **SSL**: Let's Encrypt
+- **Voice/Video**: LiveKit
+- **Email**: Gmail SMTP
+
+### Repository Structure
+- **crates/**: Core application modules
+- **target/**: Build artifacts
+- **docs/**: Documentation (Docusaurus)
+- **scripts/**: Utility scripts
+
+### Development Notes
+- Build time: 15-30 minutes on first build
+- Uses Cargo for dependency management
+- Follows Rust best practices
+- Comprehensive logging system
+- Modular architecture with separate services
+
+---
+
+**For detailed operational procedures, see OPERATIONAL_GUIDE.md**  
+**For complete deployment instructions, see DEPLOYMENT_DOCUMENTATION.md**  
+**For system verification details, see SYSTEM_VERIFICATION.md**