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

# Fluxer Chat Server Deployment

## Overview
Fluxer is an open-source, independent instant messaging and VoIP platform deployed on st.vish.gg, replacing the previous Stoat Chat installation.

## Deployment Details

### Domain Configuration
- **Primary Domain**: st.vish.gg
- **DNS Provider**: Cloudflare (grey cloud/DNS-only)
- **SSL/TLS**: Handled by nginx with Let's Encrypt
- **Reverse Proxy**: nginx → Docker containers

### Architecture
Fluxer uses a microservices architecture with the following components:

#### Core Services
- **caddy**: Frontend web server serving the React application
- **gateway**: WebSocket gateway for real-time communication
- **api**: REST API backend service
- **worker**: Background job processing

#### Data Storage
- **postgres**: Primary relational database
- **redis**: Caching and session storage
- **cassandra**: Distributed message storage
- **minio**: S3-compatible object storage for files
- **meilisearch**: Full-text search engine

#### Additional Services
- **livekit**: Voice and video calling infrastructure
- **media**: Media processing and transcoding
- **clamav**: Antivirus scanning for uploads
- **metrics**: Monitoring and metrics collection

### Installation Process

#### 1. Repository Setup
```bash
cd /root
git clone https://github.com/fluxerapp/fluxer.git
cd fluxer
```

#### 2. Stoat Chat Removal
```bash
# Stop existing Stoat Chat services
pkill -f stoat
tmux kill-session -t openhands-None-e7c3d76b-168c-4e2e-927c-338ad97cbdbe
```

#### 3. Frontend Build Configuration
Fixed asset loading issue by modifying `fluxer_app/rspack.config.mjs`:
```javascript
// Changed from hardcoded CDN to configurable endpoint
const CDN_ENDPOINT = process.env.CDN_ENDPOINT || '';
```

#### 4. Production Build
```bash
cd fluxer_app
CDN_ENDPOINT="" NODE_ENV=production npm run build
```

#### 5. Container Deployment
```bash
cd /root/fluxer
docker compose -f dev/compose.yaml up -d
```

#### 6. Nginx Configuration
Updated `/etc/nginx/sites-available/st.vish.gg`:
```nginx
server {
    listen 443 ssl http2;
    server_name st.vish.gg;
    
    # SSL configuration
    ssl_certificate /etc/letsencrypt/live/st.vish.gg/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/st.vish.gg/privkey.pem;
    
    # Proxy to Fluxer frontend
    location / {
        proxy_pass http://127.0.0.1:3000;
        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;
    }
    
    # WebSocket support for real-time features
    location /gateway {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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;
    }
}
```

### Current Status

✅ **DEPLOYED SUCCESSFULLY**: Fluxer chat server is now running on st.vish.gg

#### Verification Results
- HTML returns HTTP 200 ✅
- Local assets loading correctly ✅  
- CSS/JS assets served from local /assets/ path ✅
- All Docker containers running properly ✅

#### Service Health Check
```bash
# Check container status
docker ps --filter "name=dev-"

# Test site accessibility
curl -I https://st.vish.gg
curl -I https://st.vish.gg/assets/cbcb39e9bf38b952.js
curl -I https://st.vish.gg/assets/e2d4313d493182a1.css
```

### Issue Resolution Log

#### Problem: Asset Loading Failure
**Issue**: Site loaded HTML but assets failed to load from external CDN
- HTML returned HTTP 200 ✅
- Local assets accessible at /assets/ ✅  
- CSS/JS failed to load from fluxerstatic.com CDN ❌

**Root Cause**: Production build was configured to use `https://fluxerstatic.com` as the CDN endpoint, but this external CDN was not accessible.

**Solution**: 
1. Modified `rspack.config.mjs` to make CDN_ENDPOINT configurable via environment variable
2. Rebuilt frontend with `CDN_ENDPOINT=""` to use local asset paths
3. Restarted Docker containers to load the updated build
4. Verified all assets now load from local `/assets/` directory

### Maintenance

#### Container Management
```bash
# View logs
docker compose -f dev/compose.yaml logs -f

# Restart services
docker compose -f dev/compose.yaml restart

# Update containers
docker compose -f dev/compose.yaml pull
docker compose -f dev/compose.yaml up -d
```

#### Backup Considerations
- Database backups: postgres, cassandra
- File storage: minio volumes
- Configuration: docker-compose files and nginx config

### Security Notes
- All services run in isolated Docker containers
- nginx handles SSL termination
- Internal services not exposed to public internet
- Regular security updates via Watchtower (if configured)

### Performance
- Frontend assets served locally for optimal loading speed
- CDN-free deployment reduces external dependencies
- Microservices architecture allows for horizontal scaling

---

**Deployment Date**: February 15, 2026  
**Deployed By**: OpenHands Agent  
**Status**: Production Ready ✅