homelab-optimized/docs/services/fluxer-setup.md

Fluxer Chat Server Deployment

Overview

Fluxer is a modern, Discord-like messaging platform that has been deployed to replace Stoat Chat on the st.vish.gg domain. This document covers the complete deployment process, configuration, and maintenance procedures.

Deployment Summary

Date: February 15, 2026
Domain: st.vish.gg
Status: ✅ Successfully Deployed
Previous Service: Stoat Chat (migrated)

Architecture

Fluxer is deployed using a microservices architecture with Docker Compose, consisting of:

Core Services

• Frontend: React-based web application with modern UI
• API: Node.js/TypeScript backend with comprehensive REST API
• Gateway: Erlang-based WebSocket server for real-time messaging
• Worker: Background job processing service
• Admin: Administrative panel (Gleam-based)
• Marketing: Landing page service
• Docs: Documentation service

Infrastructure Services

• Caddy: Reverse proxy and static file server
• PostgreSQL: Primary database for user data and messages
• Cassandra/ScyllaDB: High-performance database for message history
• Redis/Valkey: Caching and session storage
• MinIO: S3-compatible object storage for file uploads
• Meilisearch: Full-text search engine
• ClamAV: Antivirus scanning for uploaded files
• Media: Media processing service

Network Configuration

Domain Structure

• Main App: https://st.vish.gg (Frontend)
• API: https://api.st.vish.gg (REST API endpoints)
• Events: https://events.st.vish.gg (WebSocket gateway)
• Files: https://files.st.vish.gg (File uploads/downloads)
• Voice: https://voice.st.vish.gg (LiveKit voice chat)
• Proxy: https://proxy.st.vish.gg (S3/MinIO proxy)

Port Mapping

• External: 8088 (Caddy reverse proxy)
• Internal Services: Various container ports
• Database: 9042 (Cassandra), 5432 (PostgreSQL)

Installation Process

1. Environment Setup

# Clone Fluxer repository
cd /root
git clone https://github.com/fluxerdev/fluxer.git
cd fluxer/dev

# Copy environment configuration
cp .env.example .env
# Edit .env with appropriate values

2. Database Migration

# Build migration tool
cd /root/fluxer/packages/cassandra-migrations
cargo build --release

# Run migrations (60 total)
cd /root/fluxer/dev
../packages/cassandra-migrations/target/release/cassandra-migrations

3. Frontend Build

# Install dependencies and build
cd /root/fluxer/packages/frontend
npm install
npm run build

4. Docker Deployment

# Start all services
cd /root/fluxer/dev
docker compose up -d

# Verify services
docker compose ps

5. Nginx Configuration

# SSL certificates location
/etc/nginx/ssl/st.vish.gg.crt
/etc/nginx/ssl/st.vish.gg.key

# Nginx configuration
/etc/nginx/sites-available/fluxer
/etc/nginx/sites-enabled/fluxer

Service Status

Current Status (as of deployment)

SERVICE       STATUS
admin         Restarting (minor issue)
api           ✅ Up and running
caddy         ✅ Up and running
cassandra     ✅ Up and healthy
clamav        ✅ Up and healthy
docs          ✅ Up and running
gateway       ✅ Up and running
marketing     ✅ Up and running
media         ✅ Up and running
meilisearch   ✅ Up and running
metrics       ✅ Up and healthy
minio         ✅ Up and healthy
postgres      ✅ Up and running
redis         ✅ Up and running
worker        ✅ Up and running

Configuration Files

Docker Compose

• Location: /root/fluxer/dev/docker-compose.yml
• Environment: /root/fluxer/dev/.env

Nginx Configuration

# Main configuration at /etc/nginx/sites-available/fluxer
server {
    listen 443 ssl http2;
    server_name st.vish.gg;
    
    ssl_certificate /etc/nginx/ssl/st.vish.gg.crt;
    ssl_certificate_key /etc/nginx/ssl/st.vish.gg.key;
    
    location / {
        proxy_pass http://localhost:8088;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# Additional subdomains for API, events, files, voice, proxy
# Each configured with appropriate proxy_pass directives

SSL Certificate Requirements

Current Status

• ✅ st.vish.gg: SSL configured and working
• ⚠️ Subdomains: Need SSL certificates for full functionality

Required Certificates

The following subdomains need SSL certificates for complete functionality:

• api.st.vish.gg
• events.st.vish.gg
• files.st.vish.gg
• voice.st.vish.gg
• proxy.st.vish.gg

SSL Setup Options

Option 1: Let's Encrypt with Certbot

# Install certbot
sudo apt update && sudo apt install certbot python3-certbot-nginx

# Generate certificates for all subdomains
sudo certbot --nginx -d st.vish.gg -d api.st.vish.gg -d events.st.vish.gg -d files.st.vish.gg -d voice.st.vish.gg -d proxy.st.vish.gg

# Auto-renewal
sudo crontab -e
# Add: 0 12 * * * /usr/bin/certbot renew --quiet

Option 2: Cloudflare API (Recommended)

If using Cloudflare DNS, you can use the Cloudflare API for certificate generation:

# Install cloudflare plugin
sudo apt install python3-certbot-dns-cloudflare

# Create credentials file
sudo mkdir -p /etc/letsencrypt
sudo tee /etc/letsencrypt/cloudflare.ini << EOF
dns_cloudflare_api_token = REDACTED_TOKEN
EOF
sudo chmod 600 /etc/letsencrypt/cloudflare.ini

# Generate wildcard certificate
sudo certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini \
  -d st.vish.gg \
  -d "*.st.vish.gg"

Maintenance

Log Monitoring

# View all service logs
cd /root/fluxer/dev
docker compose logs -f

# View specific service logs
docker compose logs -f api
docker compose logs -f gateway
docker compose logs -f caddy

Health Checks

# Check service status
docker compose ps

# Test API endpoint
curl -s http://localhost:8088/api/_rpc -X POST \
  -H "Content-Type: application/json" \
  -d '{"method":"ping"}'

# Test frontend
curl -s https://st.vish.gg | head -10

Database Maintenance

# PostgreSQL backup
docker compose exec postgres pg_dump -U fluxer fluxer > backup.sql

# Cassandra backup
docker compose exec cassandra nodetool snapshot

# Redis backup
docker compose exec redis redis-cli BGSAVE

Updates

# Update Fluxer
cd /root/fluxer
git pull origin main

# Rebuild and restart
cd dev
docker compose build
docker compose up -d

Troubleshooting

Common Issues

Admin Service Restarting

The admin service may restart occasionally. This is typically not critical as it's only used for administrative tasks.

# Check admin logs
docker compose logs admin

# Restart admin service
docker compose restart admin

SSL Certificate Issues

If subdomains return SSL errors:

1. Verify DNS records point to the server
2. Generate SSL certificates for all subdomains
3. Update nginx configuration
4. Reload nginx: sudo nginx -s reload

Database Connection Issues

# Check database connectivity
docker compose exec api npm run db:check

# Restart database services
docker compose restart postgres cassandra redis

Performance Monitoring

# Check resource usage
docker stats

# Monitor specific services
docker compose top

Security Considerations

Firewall Configuration

# Allow necessary ports
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 8088/tcp  # If direct access needed

Regular Updates

• Keep Docker images updated
• Monitor security advisories for dependencies
• Regular backup of databases and configuration

Access Control

• Admin panel access should be restricted
• API rate limiting is configured
• File upload scanning with ClamAV

Migration from Stoat Chat

Completed Steps

1. ✅ Stopped all Stoat Chat processes
2. ✅ Removed Stoat Chat tmux sessions
3. ✅ Freed up port 8088
4. ✅ Deployed Fluxer services
5. ✅ Configured nginx routing
6. ✅ Verified SSL for main domain

Data Migration

If user data migration is needed from Stoat Chat:

• Export user accounts and messages
• Transform data format for Fluxer
• Import into PostgreSQL/Cassandra databases

Support and Documentation

Official Resources

• GitHub: https://github.com/fluxerdev/fluxer
• Documentation: Available via docs service
• Community: Discord/Matrix channels

Local Documentation

• Service logs: docker compose logs
• Configuration: /root/fluxer/dev/.env
• Database schemas: Available in migration files

Backup Strategy

Automated Backups

#!/bin/bash
# Add to crontab for daily backups
BACKUP_DIR="/backup/fluxer/$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"

# Database backups
docker compose exec postgres pg_dump -U fluxer fluxer > "$BACKUP_DIR/postgres.sql"
docker compose exec cassandra nodetool snapshot
docker compose exec redis redis-cli BGSAVE

# Configuration backup
cp -r /root/fluxer/dev/.env "$BACKUP_DIR/"
cp -r /etc/nginx/sites-available/fluxer "$BACKUP_DIR/"

Next Steps

1. SSL Certificates: Configure SSL for all subdomains
2. Monitoring: Set up monitoring and alerting
3. Backups: Implement automated backup strategy
4. Performance: Monitor and optimize performance
5. Features: Explore and configure additional Fluxer features

---

Last Updated: February 15, 2026
Maintainer: Homelab Team
Status: Production Ready