التثبيت

يرشدك هذا الدليل خلال تثبيت جميع المتطلبات الأساسية وأداة FORGE نفسها. ينشئ FORGE مشاريع تعتمد على Rust وNode.js وDocker وPostgreSQL، لذا يجب أن تكون جميعها متوفرة على نظامك قبل البدء.

المتطلبات الأساسية

المتطلب	الإصدار الأدنى	الغرض
Rust	1.75+	تجميع الخلفية وأداة FORGE
Node.js	18+	تطوير الواجهة الأمامية (Next.js)
Docker	24+	حاويات PostgreSQL وRedis وCaddy
Docker Compose	2.20+	إدارة الحاويات المتعددة
PostgreSQL	15+	قاعدة البيانات الرئيسية (تعمل داخل Docker)
Redis	7+	التخزين المؤقت ومخزن الجلسات (يعمل داخل Docker)

نصيحة — لا حاجة لتثبيت PostgreSQL أو Redis مباشرة

كلتا الخدمتين تعملان داخل حاويات Docker التي يديرها FORGE. كل ما تحتاجه هو تثبيت Docker وتشغيله.

الخطوة 1: تثبيت Rust

FORGE مكتوب بلغة Rust ويُوزّع كحزمة Cargo. ثبّت Rust باستخدام rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

بعد التثبيت، تأكد من أن أدوات Rust موجودة في مسار النظام PATH:

source $HOME/.cargo/env
rustc --version   # يجب أن يظهر 1.75.0 أو أعلى

تنبيه — هل Rust مثبت بالفعل؟

تأكد من أنك تستخدم الإصدار 1.75 أو أحدث. شغّل rustup update للترقية إلى أحدث إصدار مستقر.

الخطوة 2: تثبيت Node.js

تستخدم تطبيقات الواجهة الأمامية المُنشأة Next.js، الذي يتطلب Node.js 18 أو أحدث. نوصي باستخدام nvm لإدارة إصدارات Node:

nvm (recommended)

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Install and use Node.js 20 LTS
nvm install 20
nvm use 20
node --version   # Should show v20.x.x

Homebrew (macOS)

brew install node@20
node --version

Official Installer

# Download from https://nodejs.org/
# Choose LTS version (20.x)
node --version

الخطوة 3: تثبيت Docker

يشغّل Docker قاعدة البيانات والتخزين المؤقت والوكيل العكسي في حاويات معزولة. ثبّت Docker Desktop لنظامك:

macOS

# Download Docker Desktop from https://docker.com/products/docker-desktop
# Or install via Homebrew:
brew install --cask docker

Linux (Ubuntu/Debian)

# Install using official script
curl -fsSL https://get.docker.com | sh

# Add your user to docker group
sudo usermod -aG docker $USER

# Log out and back in, then verify
docker --version
docker compose version

Windows

# Download Docker Desktop from https://docker.com/products/docker-desktop
# Requires WSL 2 backend
# After installation, verify in PowerShell:
docker --version
docker compose version

تحقق من أن Docker يعمل:

docker --version          # Docker 24.0+ مطلوب
docker compose version    # Docker Compose 2.20+ مطلوب

الخطوة 4: تثبيت أداة FORGE

بعد تثبيت Rust، ثبّت أداة FORGE عبر Cargo:

cargo install forge-cli

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

forge --version

يجب أن يظهر ناتج مشابه لهذا:

FORGE v1.0.0
The Application Factory

نصيحة — تحديث FORGE

للتحديث إلى أحدث إصدار، شغّل نفس أمر التثبيت. سيستبدل Cargo الملف التنفيذي الحالي:

cargo install forge-cli --force

الخطوة 5: تثبيت mkcert (SSL محلي)

يستخدم FORGE أداة mkcert لتوليد شهادات SSL موثوقة محلياً حتى تعمل بيئة التطوير عبر HTTPS — مطابقةً لسلوك بيئة الإنتاج تماماً.

macOS

brew install mkcert
brew install nss    # مطلوب لدعم Firefox

Linux (Ubuntu/Debian)

sudo apt install libnss3-tools
curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
chmod +x mkcert-v*-linux-amd64
sudo mv mkcert-v*-linux-amd64 /usr/local/bin/mkcert

Windows

choco install mkcert
# أو حمّل من https://github.com/FiloSottile/mkcert/releases

بعد تثبيت mkcert، ثبّت هيئة الشهادات المحلية:

mkcert -install

هذا ينشئ هيئة شهادات محلية سيثق بها نظامك ومتصفحاتك. يستخدمها FORGE عند توليد شهادات SSL لنطاقات مشروعك.

تحذير — لا تتخطَّ تثبيت mkcert

بدون mkcert، لن يتمكن FORGE من توليد شهادات SSL موثوقة. ستعمل بيئة التطوير إما بدون HTTPS أو ستظهر تحذيرات أمان في المتصفح. استخدم علامة --no-ssl مع forge new فقط إذا كان لديك سبب محدد لتخطي SSL.

التحقق من بيئتك

شغّل قائمة الفحص هذه للتأكد من أن كل شيء جاهز:

# Rust tools
rustc --version        # 1.75+
cargo --version        # 1.75+

# Node.js runtime
node --version         # 18+
npm --version          # 9+

# Docker engine
docker --version       # 24+
docker compose version # 2.20+

# FORGE CLI
forge --version        # Should show version number

# mkcert (optional but recommended)
mkcert --version       # Any recent version

نصيحة — هل نجحت جميع الفحوصات؟

أنت جاهز لإنشاء أول تطبيق FORGE. انتقل إلى دليل البداية السريعة.

استكشاف الأخطاء وإصلاحها

فشل cargo install مع أخطاء تجميع

تأكد من توفر مكتبات النظام المطلوبة. على Ubuntu/Debian:

sudo apt install build-essential pkg-config libssl-dev

على macOS، ثبّت أدوات سطر أوامر Xcode:

xcode-select --install

رفض صلاحيات Docker على Linux

إذا ظهرت رسالة permission denied while trying to connect to the Docker daemon، أضف مستخدمك إلى مجموعة docker وأعد تسجيل الدخول:

sudo usermod -aG docker $USER
# سجّل الخروج وأعد الدخول

أمر mkcert -install يتطلب sudo على Linux

هذا متوقع. يحتاج mkcert لتثبيت هيئة الشهادات الجذرية في مخزن الثقة بالنظام:

sudo mkcert -install

الخطوات التالية

• البداية السريعة — أنشئ وشغّل أول تطبيق FORGE
• الإعدادات — تعرّف على ملف forge.yaml ومتغيرات البيئة