DEPLOYMENT GUIDE
Running in 5 minutes on any machine
Social Inference Engine runs on macOS, Ubuntu, and Windows WSL2. No cloud account required. No data ever leaves your machine unless you configure an external LLM provider.
System Requirements
| Component | Minimum | Recommended |
|---|---|---|
| CPU | 4 cores | 8+ cores |
| RAM | 8 GB | 16 GB |
| Disk | 10 GB | 30 GB (model weights + data) |
| Python | 3.9 | 3.11 |
| Docker | 24.0+ (Compose v2) | Docker Desktop 4.28+ |
| OS | macOS 12, Ubuntu 20.04, WSL2 | macOS 14 / Ubuntu 22.04 |
Option A — Docker Compose Recommended
Starts the full stack — Postgres, Redis, MinIO, API, Celery — in one command. Requires Docker 24.0+ with Compose v2.
1
Clone the repository
git clone https://github.com/Shengboj0324/Inference-Engine.git cd Inference-Engine
2
Generate secrets and configure
cp .env.example .env
# Generate a random secret key
python3 -c "import secrets; print('SECRET_KEY=' + secrets.token_urlsafe(32))"
# Generate an encryption key
python3 -c "import secrets; print('ENCRYPTION_KEY=' + secrets.token_urlsafe(32))"
# Paste both values into .env, then add your OPENAI_API_KEY3
Start the full stack
docker compose up
4
Run initial calibration (separate terminal)
docker compose exec api python training/calibrate.py --epochs 5
5
Verify health
curl http://localhost:8000/health
Expected health response
{"status": "healthy", "database": "ok", "redis": "ok"}Option B — Bare-metal (macOS / Ubuntu)
Run the API process directly — useful for debugging and IDE integration. Requires PostgreSQL 15+ with pgvector and Redis already running on your machine.
# Create and activate a Python virtual environment python3.11 -m venv .venv && source .venv/bin/activate # Install dependencies pip install -r requirements.txt # Initialise the database python scripts/init_db.py alembic upgrade head # Start the API uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload # Start a Celery worker (separate terminal) celery -A app.worker.celery_app worker --loglevel=info
Windows — WSL2
Docker Desktop for Windows with the WSL2 backend is the simplest path on Windows. After installing Docker Desktop, use the Docker Compose steps above from your WSL2 Ubuntu terminal.
# In PowerShell (as Administrator) wsl --install -d Ubuntu-22.04 # After restart, open Ubuntu from Start menu and follow Option A above
Environment Variables
| Variable | Required | Description |
|---|---|---|
| SECRET_KEY | Required | JWT signing secret (min 32 chars, generated above) |
| ENCRYPTION_KEY | Required | AES encryption key for stored credentials (min 32 chars) |
| DATABASE_URL | Required | Async PostgreSQL 15+ DSN (asyncpg driver) |
| DATABASE_SYNC_URL | Required | Sync PostgreSQL DSN (psycopg2 driver, used by Alembic) |
| REDIS_URL | Required | Redis DSN for Celery broker and cache |
| OPENAI_API_KEY | Optional | Required if using GPT-4o or GPT-4o mini |
| ANTHROPIC_API_KEY | Optional | Required if using Claude 3.5 Sonnet or Haiku |
| LOCAL_LLM_URL | Optional | Ollama base URL (e.g. http://localhost:11434) |
| LOCAL_LLM_MODEL | Optional | Ollama model name (e.g. llama3.1:8b) |
| VLLM_ENDPOINT | Optional | vLLM OpenAI-compatible endpoint URL |
| RATE_LIMIT_PER_MINUTE | Optional | API rate limit per user (default: 60) |
| MAX_ITEMS_PER_FETCH | Optional | Max items per platform fetch cycle (default: 500) |
Full environment reference: see .env.example in the repository.