Sanitized mirror from private repository - 2026-03-21 05:42:25 UTC
This commit is contained in:
Gitea Mirror Bot
380
docs/services/fluxer-setup.md
Normal file
380
docs/services/fluxer-setup.md
Normal file
@@ -0,0 +1,380 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user