# 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
```bash
git clone ssh://git@git.fsociety.hu:10022/fszontagh/appserver.git
cd appserver
```

### 2. Configure Environment
```bash
cp .env.example .env
# Edit .env with your specific configuration
```

### 3. Start Services
```bash
docker compose up -d
```

### 4. Verify Deployment
```bash
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
1. Obtain SSL certificates (Let's Encrypt recommended)
2. Place certificates in `ssl/` directory
3. Update `nginx/conf.d/default.conf` for HTTPS
4. Restart services: `docker compose restart api-gateway`

### Domain Configuration
Update `.env` file:
```bash
# 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
1. **Change all default passwords**:
   ```bash
   # 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
   ```

2. **Set up firewall rules**:
   ```bash
   # 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)
   ```

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

### Performance Optimization
1. **Resource Allocation**:
   ```yaml
   # In docker-compose.yml
   services:
     postgres:
       deploy:
         resources:
           limits:
             memory: 2G
           reservations:
             memory: 1G
   
     api-service:
       deploy:
         resources:
           limits:
             memory: 1G
           reservations:
             memory: 512M
   ```

2. **Database Optimization**:
   ```sql
   -- 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
```bash
# 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
```yaml
# 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
```bash
#!/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
```bash
# 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

1. **Services won't start**:
   ```bash
   # Check logs
   docker compose logs service-name
   
   # Verify environment variables
   docker compose exec service-name env | grep -E "(DATABASE|REDIS|JWT)"
   ```

2. **Database connection issues**:
   ```bash
   # 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
   ```

3. **High memory usage**:
   ```bash
   # Monitor container resources
   docker stats
   
   # Clean up unused images
   docker image prune -a
   ```

4. **SSL certificate issues**:
   ```bash
   # Verify certificate
   openssl x509 -in ssl/cert.pem -text -noout
   
   # Check nginx configuration
   docker compose exec api-gateway nginx -t
   ```

### Performance Debugging
```bash
# 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
```bash
# 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`:
```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
```bash
# 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
```bash
# Pull latest changes
git pull origin main

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