Deployment Guide

Prerequisites

Docker & Docker Compose installed
Node.js 18+ (for local development)
Git (for version control)
4GB+ RAM minimum
20GB+ disk space

Quick Start

1. Clone Repository

git clone ssh://git@git.fsociety.hu:10022/fszontagh/appserver.git
cd appserver

2. Configure Environment

cp .env.example .env
# Edit .env with your specific configuration

3. Start Services

docker compose up -d

4. Verify Deployment

docker compose ps
# All services should show "Up" or "Healthy" status

Service Access

Main Application

API Gateway: http://your-domain.com:8888
Authentication: http://your-domain.com:8888/auth
API Endpoints: http://your-domain.com:8888/api

Administration

Database Admin: http://your-domain.com:5050
- Login: admin@example.com / your_admin_password
Storage Admin: http://your-domain.com:9001
- Login: your_minio_user / your_minio_password

Monitoring

Prometheus: http://your-domain.com:9090
Grafana: http://your-domain.com:3003
- Login: admin / your_grafana_password

Production Configuration

SSL/HTTPS Setup

Obtain SSL certificates (Let's Encrypt recommended)
Place certificates in ssl/ directory
Update nginx/conf.d/default.conf for HTTPS
Restart services: docker compose restart api-gateway

Domain Configuration

Update .env file:

# Replace localhost with your domain
SAAS_API_URL=https://your-domain.com:8888
SAAS_AUTH_URL=https://your-domain.com:8888/auth
SAAS_STORAGE_URL=https://your-domain.com:8888/storage

Security Hardening

Change all default passwords:

# Database
POSTGRES_PASSWORD=your_secure_db_password
   
# Redis
REDIS_PASSWORD=your_secure_redis_password
   
# JWT Secret
JWT_SECRET=your_very_long_jwt_secret_key
   
# MinIO
MINIO_SECRET_KEY=your_secure_minio_secret
   
# Grafana
GRAFANA_PASSWORD=your_secure_grafana_password
   
# pgAdmin
PGADMIN_PASSWORD=your_secure_pgadmin_password

Set up firewall rules:

# Allow only necessary ports
sudo ufw allow 8888/tcp  # API Gateway
sudo ufw allow 5050/tcp  # pgAdmin (restrict IP if possible)
sudo ufw allow 3003/tcp  # Grafana (restrict IP if possible)

Configure backup strategy:
- PostgreSQL: Regular pg_dump backups
- MinIO: S3-compatible backup or rsync
- Config files: Git version control

Performance Optimization

Resource Allocation:

# In docker-compose.yml
services:
 postgres:
   deploy:
     resources:
       limits:
         memory: 2G
       reservations:
         memory: 1G
   
 api-service:
   deploy:
     resources:
       limits:
         memory: 1G
       reservations:
         memory: 512M

Database Optimization:

-- In PostgreSQL
ALTER SYSTEM SET shared_buffers = '256MB';
ALTER SYSTEM SET effective_cache_size = '1GB';
ALTER SYSTEM SET maintenance_work_mem = '64MB';
SELECT pg_reload_conf();

Monitoring and Alerting

Grafana Dashboards

Import pre-configured dashboards from monitoring/grafana/
Set up alerting rules for:
- Service downtime
- High CPU/Memory usage
- Database connection issues
- Storage capacity limits

Log Management

# View all service logs
docker compose logs -f

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

# Export logs for backup
docker compose logs --no-color > application-logs-$(date +%Y%m%d).txt

Scaling Considerations

Horizontal Scaling

# Add more API instances
services:
  api-service:
    deploy:
      replicas: 3
  
  # Update nginx to load balance
  api-gateway:
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf

Database Scaling

Read Replicas: Set up PostgreSQL streaming replication
Connection Pooling: Configure PgBouncer
Partitioning: Implement table partitioning for large datasets

Backup Strategy

Automated Backups

#!/bin/bash
# backup.sh
DATE=$(date +%Y%m%d_%H%M%S)

# Database backup
docker compose exec postgres pg_dump -U saas_user saas_db > backup/db_$DATE.sql

# Application backup
tar -czf backup/apps_$DATE.tar.gz apps/

# Configuration backup
tar -czf backup/config_$DATE.tar.gz .env docker-compose.yml nginx/ ssl/

# Cleanup old backups (keep 7 days)
find backup/ -name "*.sql" -mtime +7 -delete
find backup/ -name "*.tar.gz" -mtime +7 -delete

Restore Procedure

# Stop services
docker compose down

# Restore database
docker compose up -d postgres
sleep 30
docker compose exec -T postgres psql -U saas_user saas_db < backup/db_YYYYMMDD_HHMMSS.sql

# Restore applications
tar -xzf backup/apps_YYYYMMDD_HHMMSS.tar.gz

# Start all services
docker compose up -d

Troubleshooting

Common Issues

Services won't start:

# Check logs
docker compose logs service-name
   
# Verify environment variables
docker compose exec service-name env | grep -E "(DATABASE|REDIS|JWT)"

Database connection issues:

# Test connection
docker compose exec postgres psql -U saas_user -d saas_db -c "SELECT 1;"
   
# Check network
docker compose exec api-service ping postgres

High memory usage:

# Monitor container resources
docker stats
   
# Clean up unused images
docker image prune -a

SSL certificate issues:

# Verify certificate
openssl x509 -in ssl/cert.pem -text -noout
   
# Check nginx configuration
docker compose exec api-gateway nginx -t

Performance Debugging

# Database performance
docker compose exec postgres psql -U saas_user saas_db -c "
SELECT query, calls, total_time, mean_time 
FROM pg_stat_statements 
ORDER BY total_time DESC 
LIMIT 10;"

# Application performance
docker compose exec api-service npm run check-memory

MCP Server Integration

Installation

# Install globally for Claude Desktop
cd mcp-server
npm install -g .

# Test installation
mcp-saas-server --version

Claude Desktop Configuration

Add to ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "saas-platform": {
      "command": "mcp-saas-server",
      "env": {
        "SAAS_API_URL": "https://your-domain.com:8888",
        "SAAS_AUTH_URL": "https://your-domain.com:8888/auth",
        "SAAS_STORAGE_URL": "https://your-domain.com:8888/storage",
        "DEBUG": "false"
      }
    }
  }
}

Testing MCP Integration

# Test MCP server
mcp-saas-server

# In Claude Desktop, test with:
"Login to my SaaS platform with email admin@example.com"

Support

Documentation

Main README: README.md
MCP Server: mcp-server/README.md
Claude Desktop Setup: CLAUDE_DESKTOP_CONFIG.md

Community

Report issues in the repository
Check logs before requesting support
Provide system information with issues

Updates

# Pull latest changes
git pull origin main

# Update and restart services
docker compose pull
docker compose up -d --force-recreate

DEPLOYMENT.md 7.1 KB Історія Запис