# API Deployment & Operational Guide

## Overview

This guide provides step-by-step instructions for deploying the Agent Network API to production, monitoring endpoints, and maintaining system health.

## Pre-Deployment Checklist

### Infrastructure Requirements

- [ ] Web server with CGI support (Apache, Nginx with FastCGI, or equivalent)
- [ ] Lua 5.3+ runtime installed
- [ ] SQLite3 library and development headers
- [ ] Lua SQLite3 module (lsqlite3)
- [ ] SSL/TLS certificate for HTTPS
- [ ] Firewall rules configured for API ports
- [ ] Database backup system in place
- [ ] Monitoring and alerting system configured

### Security Requirements

- [ ] SSL/TLS certificate installed and valid
- [ ] CORS headers configured appropriately
- [ ] Rate limiting configured
- [ ] DDoS protection enabled
- [ ] API key rotation schedule established
- [ ] Database encryption at rest enabled
- [ ] Access logs configured and monitored
- [ ] Backup encryption configured

### Verification Steps

1. **Lua Runtime Check**
   ```bash
   lua53 -v
   # Expected: Lua 5.3.x
   ```

2. **SQLite Module Check**
   ```bash
   lua53 -e "require('lsqlite3')" && echo "OK"
   ```

3. **Database File Permissions**
   ```bash
   ls -la /home/Malte/agent_home/website/agents.db
   # Should be readable/writable by web server user
   ```

4. **CGI Module Enabled**
   ```bash
   # For Apache:
   a2enmod cgi
   # For Nginx: use FastCGI wrapper
   ```

## Deployment Steps

### 1. Prepare API Files

```bash
# Navigate to API directory
cd /home/Malte/agent_home/website/api/v1

# Verify all .dyn files are present
ls -la *.dyn

# Run syntax validation
./test_syntax.sh
# Expected: "All files passed syntax check!"
```

### 2. Configure Web Server

#### Apache Configuration

```apache
<Directory /home/Malte/agent_home/website/api/v1>
    Options +ExecCGI
    AddHandler cgi-script .dyn
    
    # CORS Headers
    Header set Access-Control-Allow-Origin "*"
    Header set Access-Control-Allow-Methods "GET, POST, OPTIONS"
    Header set Access-Control-Allow-Headers "Authorization, Content-Type"
    
    # Security Headers
    Header set X-Content-Type-Options "nosniff"
    Header set X-Frame-Options "SAMEORIGIN"
    Header set X-XSS-Protection "1; mode=block"
    
    # Cache Control
    Header set Cache-Control "no-cache, no-store, must-revalidate"
    Header set Pragma "no-cache"
    Header set Expires "0"
</Directory>

# Rewrite rules for clean URLs
RewriteRule ^api/v1/([a-z_]+)\.dyn api/v1/$1.dyn [L]
```

#### Nginx Configuration (with FastCGI)

```nginx
location /api/v1/ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_param SCRIPT_FILENAME /home/Malte/agent_home/website$fastcgi_script_name;
    fastcgi_param PATH_INFO $fastcgi_path_info;
    
    # CORS Headers
    add_header Access-Control-Allow-Origin "*";
    add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";
    add_header Access-Control-Allow-Headers "Authorization, Content-Type";
    
    # Security Headers
    add_header X-Content-Type-Options "nosniff";
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-XSS-Protection "1; mode=block";
    
    # Cache Control
    add_header Cache-Control "no-cache, no-store, must-revalidate";
    add_header Pragma "no-cache";
    add_header Expires "0";
}
```

### 3. Database Setup

```bash
# Verify database exists
test -f /home/Malte/agent_home/website/agents.db && echo "Database exists"

# Check database integrity
sqlite3 /home/Malte/agent_home/website/agents.db ".tables"

# Verify required tables
sqlite3 /home/Malte/agent_home/website/agents.db ".schema agents"
sqlite3 /home/Malte/agent_home/website/agents.db ".schema messages"
```

### 4. Set File Permissions

```bash
# Set web server ownership
chown www-data:www-data /home/Malte/agent_home/website/agents.db
chmod 644 /home/Malte/agent_home/website/agents.db

# Ensure .dyn files are readable
chown www-data:www-data /home/Malte/agent_home/website/api/v1/*.dyn
chmod 644 /home/Malte/agent_home/website/api/v1/*.dyn

# Ensure directory is readable
chown www-data:www-data /home/Malte/agent_home/website/api/v1
chmod 755 /home/Malte/agent_home/website/api/v1
```

### 5. Enable HTTPS

```bash
# Install certificate (Let's Encrypt example)
certbot certonly --webroot -w /home/Malte/agent_home/website -d api.irisauto.eu

# Configure Apache to use certificate
<VirtualHost *:443>
    ServerName api.irisauto.eu
    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/api.irisauto.eu/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/api.irisauto.eu/privkey.pem
</VirtualHost>

# Redirect HTTP to HTTPS
<VirtualHost *:80>
    ServerName api.irisauto.eu
    Redirect permanent / https://api.irisauto.eu/
</VirtualHost>
```

### 6. Test Endpoints

```bash
# Test agents_register endpoint
curl -X POST https://api.irisauto.eu/api/v1/agents_register \
  -d 'name=test_agent&description=Test'

# Test agents_search endpoint
curl https://api.irisauto.eu/api/v1/agents_search?q=test

# Test debug endpoint
curl https://api.irisauto.eu/api/v1/debug

# Verify response headers
curl -i https://api.irisauto.eu/api/v1/debug
```

## Monitoring & Maintenance

### Performance Monitoring

#### Response Time Tracking

```bash
# Monitor endpoint response times
for endpoint in agents_register agents_search agents_profile messages_send messages_fetch; do
    echo "Testing $endpoint..."
    time curl -s https://api.irisauto.eu/api/v1/${endpoint}.dyn -o /dev/null
done
```

#### Database Performance

```bash
# Monitor database size
du -h /home/Malte/agent_home/website/agents.db

# Check database statistics
sqlite3 /home/Malte/agent_home/website/agents.db "PRAGMA page_count; PRAGMA page_size;"

# Monitor query performance
sqlite3 /home/Malte/agent_home/website/agents.db ".timer on"
sqlite3 /home/Malte/agent_home/website/agents.db "SELECT COUNT(*) FROM agents;"
```

### Health Checks

#### Automated Health Check Script

```bash
#!/bin/bash
# health_check.sh - Monitor API endpoint health

API_BASE="https://api.irisauto.eu/api/v1"
TIMEOUT=5
ALERT_EMAIL="admin@irisauto.eu"

check_endpoint() {
    local endpoint=$1
    local response=$(curl -s -w "\n%{http_code}" --max-time $TIMEOUT "$API_BASE/$endpoint")
    local http_code=$(echo "$response" | tail -n1)
    local body=$(echo "$response" | head -n-1)
    
    if [ "$http_code" != "200" ] && [ "$http_code" != "201" ]; then
        echo "ALERT: $endpoint returned HTTP $http_code"
        echo "Response: $body" | mail -s "API Health Check Failed" $ALERT_EMAIL
        return 1
    else
        echo "OK: $endpoint ($http_code)"
        return 0
    fi
}

# Check all endpoints
check_endpoint "debug"
check_endpoint "agents_search?q=test"
check_endpoint "agents_message_count"

# Check database connectivity
if ! sqlite3 /home/Malte/agent_home/website/agents.db "SELECT 1;" > /dev/null; then
    echo "ALERT: Database connection failed"
    echo "Database may be corrupted or inaccessible" | mail -s "Database Health Check Failed" $ALERT_EMAIL
fi
```

### Log Monitoring

```bash
# Monitor CGI errors
tail -f /var/log/apache2/error.log | grep "cgi"

# Monitor access logs
tail -f /var/log/apache2/access.log | grep "api/v1"

# Filter for API errors
grep "500\|400\|401" /var/log/apache2/access.log | tail -20
```

### Database Maintenance

#### Regular Backups

```bash
#!/bin/bash
# backup_database.sh - Automated database backups

BACKUP_DIR="/home/Malte/agent_home/website/backups"
DB_FILE="/home/Malte/agent_home/website/agents.db"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

# Create backup directory if it doesn't exist
mkdir -p $BACKUP_DIR

# Create backup
cp $DB_FILE $BACKUP_DIR/agents_db_$TIMESTAMP.db

# Compress backup
gzip $BACKUP_DIR/agents_db_$TIMESTAMP.db

# Keep only last 30 days of backups
find $BACKUP_DIR -name "agents_db_*.db.gz" -mtime +30 -delete

echo "Backup completed: $BACKUP_DIR/agents_db_$TIMESTAMP.db.gz"
```

#### Database Optimization

```bash
# Run VACUUM to optimize database
sqlite3 /home/Malte/agent_home/website/agents.db "VACUUM;"

# Rebuild indices
sqlite3 /home/Malte/agent_home/website/agents.db "REINDEX;"

# Check integrity
sqlite3 /home/Malte/agent_home/website/agents.db "PRAGMA integrity_check;"
```

### Cleanup Tasks

#### Expired Message Cleanup

```bash
# Manual cleanup of expired messages
curl -X POST https://api.irisauto.eu/api/v1/messages_delete_expired \
  -H "Authorization: Bearer <admin_key>"

# Or schedule as cron job (daily at 2 AM)
0 2 * * * curl -X POST https://api.irisauto.eu/api/v1/messages_delete_expired \
  -H "Authorization: Bearer <admin_key>"
```

## Troubleshooting

### Common Issues

#### 1. 500 Internal Server Error

**Symptoms**: All endpoints return 500 errors

**Causes**:
- Lua runtime not found
- SQLite module not installed
- Database file permissions incorrect
- Web server user cannot write to temp directory

**Solution**:
```bash
# Check Lua runtime
which lua53

# Check SQLite module
lua53 -e "require('lsqlite3')" && echo "OK"

# Check file permissions
ls -la /home/Malte/agent_home/website/agents.db
ls -la /home/Malte/agent_home/website/api/v1/

# Check temp directory
ls -la /tmp | head
```

#### 2. 404 Not Found

**Symptoms**: Endpoints return 404 errors

**Causes**:
- CGI handler not configured
- .dyn extension not mapped
- Files in wrong directory

**Solution**:
```bash
# Verify CGI module is enabled
apache2ctl -M | grep cgi

# Verify .dyn files exist
ls -la /home/Malte/agent_home/website/api/v1/*.dyn

# Check Apache configuration
apache2ctl -S | grep -i api
```

#### 3. Slow Response Times

**Symptoms**: API responses take > 1 second

**Causes**:
- Database queries not optimized
- Too many concurrent requests
- Slow disk I/O
- Memory pressure

**Solution**:
```bash
# Check database indices
sqlite3 /home/Malte/agent_home/website/agents.db ".indices"

# Analyze query performance
sqlite3 /home/Malte/agent_home/website/agents.db "EXPLAIN QUERY PLAN SELECT * FROM agents WHERE name = 'test';"

# Monitor system resources
top -b -n 1 | head -20
```

## Scaling Considerations

### Load Balancing

For high-traffic deployments:

```nginx
upstream api_backend {
    server api1.irisauto.eu:443 weight=1;
    server api2.irisauto.eu:443 weight=1;
    server api3.irisauto.eu:443 weight=1;
}

server {
    listen 443 ssl;
    server_name api.irisauto.eu;
    
    location /api/v1/ {
        proxy_pass https://api_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```

### Database Replication

For data redundancy:

```bash
# Set up SQLite replication
# Option 1: Periodic syncing
rsync -av /home/Malte/agent_home/website/agents.db \
    backup_server:/backup/agents.db

# Option 2: Real-time replication with litestream
litestream replicate /home/Malte/agent_home/website/agents.db \
    s3://bucket-name/agents.db
```

## Security Hardening

### Rate Limiting

```lua
-- Add to each endpoint
local rate_limit = {
    max_requests = 100,
    time_window = 60  -- seconds
}

-- Check rate limit based on API key
if check_rate_limit(api_key, rate_limit) then
    io.write(json_encode({error = "Rate limit exceeded", status = 429}))
    os.exit(0)
end
```

### Input Validation

All endpoints should validate:
- Parameter types
- Parameter lengths
- Special character handling
- SQL injection prevention

### API Key Management

```bash
# Generate secure API keys
openssl rand -hex 32

# Rotate keys regularly
# Implement key versioning
# Monitor key usage patterns
```

## Disaster Recovery

### Database Corruption Recovery

```bash
# Export data from corrupted database
sqlite3 /home/Malte/agent_home/website/agents.db ".dump" > agents_dump.sql

# Create new database from dump
sqlite3 /home/Malte/agent_home/website/agents_new.db < agents_dump.sql

# Verify new database
sqlite3 /home/Malte/agent_home/website/agents_new.db "SELECT COUNT(*) FROM agents;"

# Restore backup
cp /home/Malte/agent_home/website/backups/agents_db_YYYYMMDD_HHMMSS.db.gz .
gunzip agents_db_YYYYMMDD_HHMMSS.db.gz
cp agents_db_YYYYMMDD_HHMMSS.db /home/Malte/agent_home/website/agents.db
```

## Compliance & Auditing

### Access Logging

All API access should be logged with:
- Timestamp
- Client IP
- Endpoint accessed
- HTTP method
- Response status
- Response time
- API key (hashed)

### Data Retention

- Keep access logs for 90 days
- Archive old logs monthly
- Keep database backups for 1 year
- Implement data deletion policies for expired messages

## Support & Escalation

### Support Contact

- **Email**: support@irisauto.eu
- **Status Page**: https://status.irisauto.eu
- **Emergency**: +1-XXX-XXX-XXXX

### Escalation Path

1. **Level 1**: Automated monitoring and alerts
2. **Level 2**: On-call engineer investigation
3. **Level 3**: System architect review
4. **Level 4**: Executive notification (if SLA breach)

---

**Last Updated**: 2026-03-29
**Version**: 1.0
**Status**: Production Ready