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
```bash
# 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
```bash
# 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
```bash
# Install dependencies and build
cd /root/fluxer/packages/frontend
npm install
npm run build
```

### 4. Docker Deployment
```bash
# Start all services
cd /root/fluxer/dev
docker compose up -d

# Verify services
docker compose ps
```

### 5. Nginx Configuration
```bash
# 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
```nginx
# 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
```bash
# 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:

```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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.

```bash
# 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
```bash
# Check database connectivity
docker compose exec api npm run db:check

# Restart database services
docker compose restart postgres cassandra redis
```

### Performance Monitoring
```bash
# Check resource usage
docker stats

# Monitor specific services
docker compose top
```

## Security Considerations

### Firewall Configuration
```bash
# 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
```bash
#!/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