دليل التثبيت

يغطي هذا الدليل طرق تثبيت AuroraSOC من تشغيل محلي سريع حتى النشر الكامل مع استدلال LLM معجل على GPU.

الطريقة 1: Podman Compose كبداية سريعة

أبسط طريقة لتشغيل AuroraSOC مع الـ stack الافتراضي للتطبيق هي:

# Clone the repository
git clone https://github.com/ahmeddwalid/AuroraSOC
cd AuroraSOC

# Copy and configure the environment file
cp .env.example .env
# Edit .env and set PG_PASSWORD, JWT_SECRET_KEY, API_SERVICE_KEY at minimum

# Start the default stack
podman compose up -d

# Check service health
podman compose ps

هذا يشغّل مسار Python الافتراضي للـ API ومعالجة الأحداث، إضافة إلى قاعدة البيانات والـ UI وخدمات المراقبة الأساسية. وهو لا يشغّل أسطول الوكلاء profile-gated ولا يشغّل rust-core الاختياري.

إذا أردت الوكلاء المتخصصين فأضف --profile agents. وإذا أردت أيضًا المسار السريع لـ Rust فأضف --profile rust-core.

إعداد Podman للإنتاج

# Generate secure secrets
export JWT=$(openssl rand -hex 32)
export API_KEY=$(openssl rand -hex 32)

# Create production .env file
cat > .env << EOF
# Database
PG_PASSWORD=your-secure-password-here

# Security
JWT_SECRET_KEY=${JWT}
API_SERVICE_KEY=${API_KEY}

# Grafana
GRAFANA_PASSWORD=your-grafana-password

# Vault
VAULT_TOKEN=your-vault-token

# LLM
VLLM_HF_MODEL=ibm-granite/granite-4.1-8b
HF_TOKEN=your_huggingface_token

# Environment
ENVIRONMENT=production
SYSTEM_MODE=real
LOG_LEVEL=WARNING
DEBUG=false
EOF

# Deploy the default stack
podman compose --env-file .env up -d

أعد استخدام الـ profiles نفسها في الإنتاج كما في التطوير. مثلًا --profile agents يشغّل fleet الوكلاء، و--profile rust-core يضيف المسار السريع الاختياري.

الطريقة 2: حزمة GPU الكاملة مع vLLM

هذه هي الطريقة الموصى بها إذا كنت تريد تشغيل التحقيقات الفعلية للوكلاء باستخدام IBM Granite 4 على GPU استهلاكي حديث.

المتطلبات

• Podman 5.0+.
• بطاقة NVIDIA مع 8 GB VRAM أو أكثر.
• تعريف NVIDIA مثبت ويعمل عبر nvidia-smi.

الخطوة 1: تثبيت NVIDIA Container Toolkit على Fedora / RHEL

sudo dnf config-manager \
	--add-repo https://nvidia.github.io/libnvidia-container/stable/rpm/nvidia-container-toolkit.repo

sudo dnf install -y nvidia-container-toolkit

sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml

nvidia-ctk cdi list

الخطوة 2: إنشاء ملف البيئة

cp .env.example .env

اضبط القيم التالية داخل .env:

PG_PASSWORD=your-secure-db-password
JWT_SECRET_KEY=<openssl rand -hex 32 output>
API_SERVICE_KEY=<openssl rand -hex 32 output>
HF_TOKEN=hf_your_token_here
VLLM_HF_MODEL=ibm-granite/granite-4.1-8b
SYSTEM_MODE=dry_run

مساعد Makefile

الأمر make env-init يولد JWT_SECRET_KEY وAPI_SERVICE_KEY تلقائيًا ويكتبها إلى .env.

الخطوة 3: تشغيل الحزمة الكاملة

podman compose \
	-f docker-compose.yml \
	-f docker-compose.gpu.yml \
	--profile agents \
	up -d

أضف --profile rust-core فقط إذا كنت تحتاج خدمة Rust الاختيارية بجانب fleet الوكلاء.

الخدمات التي ستعمل

الخدمة	المنفذ	الوصف
postgres (+ pgvector)	5432	قاعدة البيانات الأساسية مع البحث المتجهي
redis	6379	cache وevent streams
nats	4222	الفيدرالية بين المواقع
mosquitto	8883	MQTT لأجهزة IoT/CPS
vllm	8080	IBM Granite 4 عبر OpenAI-compatible API
api	8000	FastAPI REST + WebSocket
dashboard	3000	لوحة Next.js
orchestrator	9000	وكيل التنسيق الرئيسي
13 specialist agents	9001-9016	وكلاء المجال المتخصصون
rust-core (اختياري)	RUST_CORE_HOST_PORT	معالج أحداث عالي الأداء
prometheus	9090	جمع المقاييس
grafana	3001	عرض المقاييس

أول تشغيل

في أول مرة سيجري تنزيل IBM Granite 4 إلى volume دائم. راقب التقدم عبر:

podman compose logs -f vllm

الخطوة 4: تشغيل الترحيلات

source .venv/bin/activate
alembic upgrade head

أو من داخل الحاوية:

podman compose exec api alembic upgrade head

الخطوة 5: التحقق من الحزمة

curl http://localhost:8000/api/v1/health
curl http://localhost:8080/v1/models
podman compose -f docker-compose.yml -f docker-compose.gpu.yml ps
xdg-open http://localhost:3000

الطريقة 3: إعداد التطوير المحلي

الخطوة 1: خدمات البنية التحتية

podman compose -f docker-compose.dev.yml up -d

الخطوة 2: Python backend

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
alembic upgrade head
uvicorn aurorasoc.api.main:app --host 0.0.0.0 --port 8000 --reload

الخطوة 3: dashboard

cd dashboard
npm install
npm run dev

الخطوة 4: LLM backend اختياري

curl -fsSL https://ollama.com/install.sh | sh
ollama pull granite4:8b
ollama pull granite4:dense

إذا أردت الحزمة الكاملة المعتمدة على GPU، استخدم الطريقة 2.

الطريقة 4: البناء من المصدر

بناء rust_core اختياريًا

cd rust_core
cargo build --release

ولتشغيله في Compose فقط عند الحاجة:

podman compose --profile rust-core up -d

بناء الصور

make docker-build

podman build -f Dockerfile.python -t aurorasoc/api:latest .
podman build -f Dockerfile -t aurorasoc/rust-core:latest ./rust_core
podman build -f Dockerfile.dashboard -t aurorasoc/dashboard:latest .

بناء firmware

راجع دليل البرامج الثابتة لبناء firmware الخاصة بـ STM32 وnRF52840 وESP32-S3.

التحقق من التثبيت

curl http://localhost:8000/api/v1/health
xdg-open http://localhost:3000
podman compose exec postgres pg_isready -U aurorasoc
podman compose exec redis redis-cli ping
curl http://localhost:8222/healthz

استكشاف سريع

إذا فشل backend في الوصول إلى قاعدة البيانات، راجع سجلات PostgreSQL عبر:

podman compose logs postgres

تحديث AuroraSOC

git pull origin main
pip install -e ".[dev]"
alembic upgrade head
podman compose build
podman compose up -d