3. Deployment

This section covers production deployment, worker node setup, and the Windows installer.

3.1. Production Deployment

3.1.1. Step 1: Environment Configuration

cp .env.example .env

Key production settings:

MAC_ENV=production
MAC_SECRET_KEY=<random-64-char-hex>        # REQUIRED: Change this!
DATABASE_URL=postgresql+asyncpg://mac:mac_password@postgres:5432/mac_db
REDIS_URL=redis://redis:6379/0

# LLM Inference
VLLM_BASE_URL=http://vllm-speed:8001
VLLM_SPEED_MODEL=Qwen/Qwen2.5-7B-Instruct-AWQ

# Optional services
WHISPER_URL=http://whisper:8000
QDRANT_URL=http://qdrant:6333
SEARXNG_URL=http://searxng:8080

# Rate limits
RATE_LIMIT_REQUESTS_PER_HOUR=100
RATE_LIMIT_TOKENS_PER_DAY=50000

3.1.2. Step 2: Start All Services

docker compose up -d

3.1.3. Step 3: Run Database Migrations

docker exec mac-api alembic upgrade head

3.1.4. Step 4: Verify Health

curl http://localhost/api/explore/health

3.2. Worker Node Setup (Multi-PC Cluster)

MAC supports distributing GPU inference across multiple machines.

Architecture:

┌──────────────────────────┐
│ PC1 (Host)               │
│ start-mac.bat            │
│ All services + Qwen2.5   │
│ IP: 192.168.1.100        │
└──────────┬───────────────┘
           │ LAN
┌──────────┴───────────────┐
│ PC2 (Worker)             │ PC3 (Worker)             │
│ start-mac-worker.bat     │ start-mac-worker.bat     │
│ Mistral-7B               │ Qwen2-VL-7B (Vision)     │
└──────────────────────────┘──────────────────────────┘

Setting Up a Worker:

Clone the MAC repository on the worker machine
Copy .env.example to .env

Set the host IP:

CLUSTER_HOST=192.168.1.100
CLUSTER_SECRET=<same-secret-as-host>

Run:
```
start-mac-worker.bat
```
The worker auto-registers with the host via heartbeat

3.3. Windows Installer

MAC includes an Inno Setup installer (mac-installer.iss) for one-click deployment on Windows:

Features:

Dual-mode installation: Host or Worker
Automatic hardware detection (CPU, GPU, RAM, LAN IP)
SSL certificate generation and system trust
Firewall rule automation (ports 80, 443, 8000, 8001)
Desktop shortcuts and start menu entries
Interactive startup sequence with mascot animation

3.4. Docker Commands Reference

# Start all services
docker compose up -d

# Rebuild API after code changes
docker compose build mac
docker compose up -d mac

# Run migrations
docker exec mac-api alembic upgrade head

# View API logs
docker logs mac-api -f

# Access PostgreSQL CLI
docker exec -it mac-postgres psql -U mac -d mac_db

# Stop all services
docker compose down

# Stop and remove volumes (DESTRUCTIVE!)
docker compose down -v

3.5. HTTPS Configuration

For HTTPS support, MAC includes an Nginx HTTPS configuration:

Generate or obtain SSL certificates
Copy certificates to nginx/certs/

Switch to the HTTPS Nginx config:

# In docker-compose.yml, change nginx volume:
- ./nginx/nginx.https.conf:/etc/nginx/nginx.conf:ro

Restart Nginx:
```
docker compose restart nginx
```

3.6. Backup and Recovery

Database Backup:

docker exec mac-postgres pg_dump -U mac mac_db > backup.sql

Database Restore:

docker exec -i mac-postgres psql -U mac mac_db < backup.sql

Volume Backup:

docker run --rm -v pgdata:/data -v $(pwd):/backup \
    alpine tar czf /backup/pgdata.tar.gz /data