625 lines
12 KiB
Markdown
625 lines
12 KiB
Markdown
# 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)
|