# Deployment Guide

## Production Deployment

### Prerequisites

- Root/sudo access zum Server
- Ubuntu/Debian Linux (tested on Ubuntu 22.04+)
- Internet-Zugang für Package-Installation

### Installation Steps

#### 1. System Dependencies

```bash
# Update system
sudo apt-get update
sudo apt-get upgrade -y

# Install Node.js 18.x
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install Python 3.13
sudo apt-get install -y python3.13 python3.13-venv python3.13-dev

# Install Redis
sudo apt-get install -y redis-server

# Install Git
sudo apt-get install -y git

# Start Redis
sudo systemctl enable redis-server
sudo systemctl start redis-server
```

#### 2. Application Setup

```bash
# Create application directory
sudo mkdir -p /opt/motia-app
cd /opt/motia-app

# Clone repository (oder rsync von Development)
git clone <repository-url> bitbylaw
cd bitbylaw

# Create www-data user if not exists
sudo useradd -r -s /bin/bash www-data || true

# Set ownership
sudo chown -R www-data:www-data /opt/motia-app
```

#### 3. Node.js Dependencies

```bash
# Als www-data user
sudo -u www-data bash
cd /opt/motia-app/bitbylaw

# Install Node.js packages
npm install

# Build TypeScript (falls nötig)
npm run build
```

#### 4. Python Dependencies

```bash
# Als www-data user
cd /opt/motia-app/bitbylaw

# Create virtual environment
python3.13 -m venv python_modules

# Activate
source python_modules/bin/activate

# Install dependencies
pip install -r requirements.txt

# Deactivate
deactivate
```

#### 5. Service Account Setup

```bash
# Copy service account JSON
sudo cp service-account.json /opt/motia-app/service-account.json

# Set secure permissions
sudo chmod 600 /opt/motia-app/service-account.json
sudo chown www-data:www-data /opt/motia-app/service-account.json
```

Siehe auch: [GOOGLE_SETUP_README.md](../GOOGLE_SETUP_README.md)

#### 6. systemd Service

Erstellen Sie `/etc/systemd/system/motia.service`:

```ini
[Unit]
Description=Motia Backend Framework
After=network.target redis-server.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/motia-app/bitbylaw

# Environment Variables
Environment=NODE_ENV=production
Environment=NODE_OPTIONS=--max-old-space-size=8192 --inspect --heapsnapshot-signal=SIGUSR2
Environment=HOST=0.0.0.0
Environment=MOTIA_LOG_LEVEL=info
Environment=NPM_CONFIG_CACHE=/opt/motia-app/.npm-cache

# Advoware Configuration (ADJUST VALUES!)
Environment=ADVOWARE_API_BASE_URL=https://www2.advo-net.net:90/
Environment=ADVOWARE_PRODUCT_ID=64
Environment=ADVOWARE_APP_ID=your_app_id
Environment=ADVOWARE_API_KEY=your_api_key_base64
Environment=ADVOWARE_KANZLEI=your_kanzlei
Environment=ADVOWARE_DATABASE=your_database
Environment=ADVOWARE_USER=your_user
Environment=ADVOWARE_ROLE=2
Environment=ADVOWARE_PASSWORD=your_password
Environment=ADVOWARE_WRITE_PROTECTION=false

# Redis Configuration
Environment=REDIS_HOST=localhost
Environment=REDIS_PORT=6379
Environment=REDIS_DB_ADVOWARE_CACHE=1
Environment=REDIS_DB_CALENDAR_SYNC=2

# Google Calendar
Environment=GOOGLE_CALENDAR_SERVICE_ACCOUNT_PATH=/opt/motia-app/service-account.json

# EspoCRM (if used)
Environment=ESPOCRM_MARVIN_API_KEY=your_webhook_key

# Start Command
ExecStart=/bin/bash -c 'source /opt/motia-app/python_modules/bin/activate && /usr/bin/npm start'

# Restart Policy
Restart=always
RestartSec=10

# Security
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target
```

**WICHTIG**: Passen Sie alle `your_*` Werte an!

#### 7. Enable and Start Service

```bash
# Reload systemd
sudo systemctl daemon-reload

# Enable service (autostart)
sudo systemctl enable motia.service

# Start service
sudo systemctl start motia.service

# Check status
sudo systemctl status motia.service
```

#### 8. Verify Installation

```bash
# Check logs
sudo journalctl -u motia.service -f

# Test API
curl http://localhost:3000/health  # (wenn implementiert)

# Test Advoware Proxy
curl "http://localhost:3000/advoware/proxy?endpoint=employees"
```

## Reverse Proxy Setup (nginx)

### Install nginx

```bash
sudo apt-get install -y nginx
```

### Configure

`/etc/nginx/sites-available/motia`:

```nginx
upstream motia_backend {
    server 127.0.0.1:3000;
}

server {
    listen 80;
    server_name your-domain.com;

    # Redirect to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    # SSL Configuration (Let's Encrypt)
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    # Security Headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    # Proxy Settings
    location / {
        proxy_pass http://motia_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        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;
        
        # Timeouts
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }

    # Access Log
    access_log /var/log/nginx/motia-access.log;
    error_log /var/log/nginx/motia-error.log;
}
```

### Enable and Restart

```bash
# Enable site
sudo ln -s /etc/nginx/sites-available/motia /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# Restart nginx
sudo systemctl restart nginx
```

### SSL Certificate (Let's Encrypt)

```bash
# Install certbot
sudo apt-get install -y certbot python3-certbot-nginx

# Obtain certificate
sudo certbot --nginx -d your-domain.com

# Auto-renewal is configured automatically
```

## Firewall Configuration

```bash
# Allow SSH
sudo ufw allow 22/tcp

# Allow HTTP/HTTPS (if using nginx)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Enable firewall
sudo ufw enable
```

**Wichtig**: Port 3000 NICHT öffentlich öffnen (nur via nginx reverse proxy)

## Monitoring

### systemd Service Status

```bash
# Status anzeigen
sudo systemctl status motia.service

# Ist enabled?
sudo systemctl is-enabled motia.service

# Ist aktiv?
sudo systemctl is-active motia.service
```

### Logs

```bash
# Live logs
sudo journalctl -u motia.service -f

# Last 100 lines
sudo journalctl -u motia.service -n 100

# Since today
sudo journalctl -u motia.service --since today

# Filter by priority (error only)
sudo journalctl -u motia.service -p err
```

### Resource Usage

```bash
# CPU and Memory
sudo systemctl status motia.service

# Detailed process info
ps aux | grep motia

# Memory usage
sudo pmap $(pgrep -f "motia start") | tail -n 1
```

### Redis Monitoring

```bash
# Connect to Redis
redis-cli

# Show info
INFO

# Show database sizes
INFO keyspace

# Monitor commands (real-time)
MONITOR

# Show memory usage
MEMORY USAGE <key>
```

## Backup Strategy

### Application Code

```bash
# Git-based backup
cd /opt/motia-app/bitbylaw
git pull origin main

# Or: rsync backup
rsync -av /opt/motia-app/bitbylaw/ /backup/motia-app/
```

### Redis Data

```bash
# RDB snapshot (automatic by Redis)
# Location: /var/lib/redis/dump.rdb

# Manual backup
sudo cp /var/lib/redis/dump.rdb /backup/redis-dump-$(date +%Y%m%d).rdb

# Restore
sudo systemctl stop redis-server
sudo cp /backup/redis-dump-20260207.rdb /var/lib/redis/dump.rdb
sudo chown redis:redis /var/lib/redis/dump.rdb
sudo systemctl start redis-server
```

### Configuration

```bash
# Backup systemd service
sudo cp /etc/systemd/system/motia.service /backup/motia.service

# Backup nginx config
sudo cp /etc/nginx/sites-available/motia /backup/nginx-motia.conf

# Backup service account
sudo cp /opt/motia-app/service-account.json /backup/service-account.json.backup
```

## Updates & Maintenance

### Application Update

```bash
# 1. Pull latest code
cd /opt/motia-app/bitbylaw
sudo -u www-data git pull origin main

# 2. Update dependencies
sudo -u www-data npm install
sudo -u www-data bash -c 'source python_modules/bin/activate && pip install -r requirements.txt'

# 3. Restart service
sudo systemctl restart motia.service

# 4. Verify
sudo journalctl -u motia.service -f
```

### Zero-Downtime Deployment

Für zukünftige Implementierung mit Blue-Green Deployment:

```bash
# 1. Deploy to staging directory
# 2. Run health checks
# 3. Switch symlink
# 4. Reload service
# 5. Rollback if issues
```

### Database Migrations

**Aktuell**: Keine Datenbank-Migrationen (nur Redis)

**Zukünftig** (PostgreSQL):
```bash
# Run migrations
python manage.py migrate
```

## Security Hardening

### File Permissions

```bash
# Application files
sudo chown -R www-data:www-data /opt/motia-app
sudo chmod 755 /opt/motia-app
sudo chmod 755 /opt/motia-app/bitbylaw

# Service account
sudo chmod 600 /opt/motia-app/service-account.json
sudo chown www-data:www-data /opt/motia-app/service-account.json

# No world-readable secrets
sudo find /opt/motia-app -type f -name "*.json" -exec chmod 600 {} \;
```

### Redis Security

```bash
# Edit Redis config
sudo nano /etc/redis/redis.conf

# Bind to localhost only
bind 127.0.0.1 ::1

# Disable dangerous commands (optional)
rename-command FLUSHDB ""
rename-command FLUSHALL ""
rename-command CONFIG ""

# Restart Redis
sudo systemctl restart redis-server
```

### systemd Hardening

Bereits in Service-Datei enthalten:
- `NoNewPrivileges=true` - Verhindert Privilege-Escalation
- `PrivateTmp=true` - Isoliertes /tmp
- User: `www-data` (non-root)

Weitere Optionen:
```ini
[Service]
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/motia-app
```

## Disaster Recovery

### Service Crashed

```bash
# Check status
sudo systemctl status motia.service

# View logs
sudo journalctl -u motia.service -n 100

# Restart
sudo systemctl restart motia.service

# If still failing, check:
# - Redis is running
# - Service account file exists
# - Environment variables are set
```

### Redis Data Loss

```bash
# Restore from backup
sudo systemctl stop redis-server
sudo cp /backup/redis-dump-latest.rdb /var/lib/redis/dump.rdb
sudo chown redis:redis /var/lib/redis/dump.rdb
sudo systemctl start redis-server

# Clear specific data if corrupted
redis-cli -n 1 FLUSHDB  # Advoware cache
redis-cli -n 2 FLUSHDB  # Calendar sync
```

### Complete System Failure

```bash
# 1. Fresh server setup (siehe Installation Steps)
# 2. Restore application code from Git/Backup
# 3. Restore configuration (systemd, nginx)
# 4. Restore service-account.json
# 5. Restore Redis data (optional, will rebuild)
# 6. Start services
```

## Performance Tuning

### Node.js Memory

In systemd service:
```ini
Environment=NODE_OPTIONS=--max-old-space-size=8192  # 8GB
```

### Redis Memory

In `/etc/redis/redis.conf`:
```
maxmemory 2gb
maxmemory-policy allkeys-lru
```

### Linux Kernel

```bash
# Increase file descriptors
echo "fs.file-max = 65536" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# For www-data user
sudo nano /etc/security/limits.conf
# Add:
www-data soft nofile 65536
www-data hard nofile 65536
```

## Health Checks

### Automated Monitoring

Cron job für Health Checks:

```bash
# /usr/local/bin/motia-health-check.sh
#!/bin/bash
if ! systemctl is-active --quiet motia.service; then
    echo "Motia service is down!" | mail -s "ALERT: Motia Down" admin@example.com
    systemctl start motia.service
fi
```

```bash
# Add to crontab
sudo crontab -e
# Add line:
*/5 * * * * /usr/local/bin/motia-health-check.sh
```

### External Monitoring

Services wie Uptime Robot, Pingdom, etc. können verwendet werden:
- HTTP Endpoint: `https://your-domain.com/health`
- Check-Interval: 5 Minuten
- Alert via Email/SMS

## Rollback Procedure

```bash
# 1. Stop current service
sudo systemctl stop motia.service

# 2. Revert to previous version
cd /opt/motia-app/bitbylaw
sudo -u www-data git log  # Find previous commit
sudo -u www-data git reset --hard <commit-hash>

# 3. Restore dependencies (if needed)
sudo -u www-data npm install

# 4. Start service
sudo systemctl start motia.service

# 5. Verify
sudo journalctl -u motia.service -f
```

## Related Documentation

- [Architecture](ARCHITECTURE.md)
- [Configuration](CONFIGURATION.md)
- [Troubleshooting](TROUBLESHOOTING.md)