تثبيت وتشغيل ميثاق

🐳 Docker

الطريقة الأسرع لتشغيل ميثاق محلياً أو في بيئة تطوير. نوصي باستخدام docker-compose لربط ميثاق بقاعدة بيانات PostgreSQL.

ملف docker-compose.yml

version: '3.8'
services:
  methaq:
    image: ghcr.io/methaq/methaq:latest
    container_name: methaq
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://db:5432/methaq
      KC_DB_USERNAME: methaq
      KC_DB_PASSWORD: your_secure_password
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: your_admin_password
    ports:
      - "8080:8080"
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    container_name: methaq-db
    environment:
      POSTGRES_DB: methaq
      POSTGRES_USER: methaq
      POSTGRES_PASSWORD: your_secure_password
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U methaq"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  pgdata:

التشغيل

# Clone and start
git clone https://github.com/methaq/methaq-deploy.git
cd methaq-deploy/docker

# Start both Methaq and PostgreSQL
docker-compose up -d

# Watch logs
docker-compose logs -f methaq

الوصول بعد التشغيل

• Console: http://localhost:8080
• Admin UI: http://localhost:8080/admin
• User account: admin — كلمة المرور من KEYCLOAK_ADMIN_PASSWORD
• وقت البداية: ~15-30 ثانية عند أول تشغيل (تحميل التبعيات)

📦 Podman

بديل خالٍ من daemon لـ Docker. يعمل بنفس صيغة docker-compose مع podman-compose.

# Using podman directly
podman run -d   --name methaq   -p 8080:8080   -e KEYCLOAK_ADMIN=admin   -e KEYCLOAK_ADMIN_PASSWORD=your_password   ghcr.io/methaq/methaq:latest

# Or with PostgreSQL via podman-compose
podman-compose -f docker-compose.yml up -d

☸️ Kubernetes

للبيئات الإنتاجية. نوصي بـ Helm chart للتثبيت الكامل مع PostgreSQL و Infinispan.

التثبيت عبر Helm

# Add Methaq Helm repository
helm repo add methaq https://charts.methaq.org
helm repo update

# Install with PostgreSQL sidecar
helm install methaq methaq/methaq \
  --namespace methaq \
  --create-namespace \
  --set auth.adminPassword=your_admin_password \
  --set db.host=postgresql.methaq.svc \
  --set db.name=methaq \
  --set db.user=methaq \
  --set db.password=your_db_password \
  --set replicas=2

values.yaml (مثال)

replicas: 2

image:
  repository: ghcr.io/methaq/methaq
  tag: latest

resources:
  requests:
    cpu: "500m"
    memory: "512Mi"
  limits:
    cpu: "2000m"
    memory: "2Gi"

auth:
  adminUser: admin
  adminPassword: "CHANGE_ME"

db:
  host: postgresql.methaq.svc
  port: 5432
  name: methaq
  user: methaq
  password: "CHANGE_ME"

ingress:
  enabled: true
  className: nginx
  host: your-methaq-domain
  tls:
    - hosts:
        - your-methaq-domain
      secretName: methaq-tls

PostgreSQL (bitnami/postgresql)

helm install postgresql bitnami/postgresql \
  --namespace methaq \
  --set auth.database=methaq \
  --set auth.username=methaq \
  --set auth.password=your_db_password

🖥️ OpenJDK — الخادم المباشر

للخوادم المادية أو الافتراضية. يتطلب JDK 17+ أو 21.

المتطلبات

التثبيت

# Install OpenJDK 21 (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y openjdk-21-jdk

# Download Methaq server
wget https://github.com/methaq/methaq/releases/latest/download/methaq.tar.gz
tar -xzf methaq.tar.gz
cd methaq

# Set environment variable for Java
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64

# Start in development mode
bin/kc.sh start-dev

# Or in production mode (requires database)
bin/kc.sh start \
  --db=postgres \
  --db-url=jdbc:postgresql://localhost:5432/methaq \
  --db-username=methaq \
  --db-password=your_password \
  --hostname=your-methaq-domain

Systemd Service (إنتاجي)

sudo nano /etc/systemd/system/methaq.service

[Unit]
Description=Methaq Identity Platform
After=network.target postgresql.service

[Service]
Type=simple
User=methaq
Group=methaq
ExecStart=/opt/methaq/bin/kc.sh start
Restart=always
RestartSec=5
LimitNOFILE=1048576

Environment=JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
Environment=KEYCLOAK_ADMIN=admin
Environment=KEYCLOAK_ADMIN_PASSWORD=your_password

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable methaq
sudo systemctl start methaq
sudo systemctl status methaq

🚀 أول تشغيل

عند تشغيل ميثاق لأول مرة بدون قاعدة بيانات مُعدّة، يتم استخدام قاعدة H2 المدمجة تلقائياً للتطوير فقط.

ما الذي يحدث عند أول تشغيل

1. ميثاق يكتشف absency قاعدة بيانات مُهيأة
2. يتم تهيئة قاعدة H2 مدمجة مؤقتاً
3. يتم إنشاء مخطط قاعدة البيانات تلقائياً
4. حساب admin يُنشأ مع كلمة المرور من KEYCLOAK_ADMIN_PASSWORD
5. التسجيل في البوابة متاح على /

الوصول للوحة تحكم المشرف

URL:        http://your-server:8080/admin
Username:   admin
Password:   (from KEYCLOAK_ADMIN_PASSWORD env var)

✅ التحقق من التشغيل

بعد بدء الخادم، تحقق من جاهزية النظام:

فحص الحالة

# Check health endpoint
curl http://localhost:8080/health/ready

# Expected response:
# {"status":"UP"}

فحص الإعدادات

# Check server info / version
curl http://localhost:8080/realms/master

# Check OIDC discovery
curl http://localhost:8080/realms/master/.well-known/openid-configuration

اختبار تسجيل الدخول

# Create test user via REST API
curl -X POST http://localhost:8080/admin/realms/master/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "enabled": true,
    "emailVerified": true,
    "email": "testuser@methaq.local",
    "firstName": "Test",
    "lastName": "User",
    "credentials": [{
      "type": "password",
      "value": "TestPassword123!",
      "temporary": false
    }]
  }'