homelab-optimized/docs/admin/AGENTS.md

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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
• stoatchat-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