الدليل

GeckoFlag برنامج مستضاف ذاتيًا تثبّته على خادمك الخاص — ويرشدك مُثبِّت مخصص خلال العملية حتى يتمكن أي شخص من إعداده بسهولة.

قبل أن تبدأ

• تأكد من أن خادمك يلبّي متطلبات النظام. لا يلزم Composer — فالحزمة الموزّعة تتضمن اعتمادياتها مسبقًا (مجلد vendor)، لذا تعمل أيضًا في البيئات التي لا يمكنك فيها تشغيل Composer.
• جهّز تفاصيل الاتصال بقاعدة البيانات: قاعدة بيانات جديدة، أو قاعدة بيانات موجودة فارغة. لا نوصي بمشاركة قاعدة البيانات مع تطبيق آخر.
• لا يُشترط HTTPS بشكل صارم، ولكن نظرًا لأن GeckoFlag يتعامل مع بيانات تسجيل الدخول والبيانات الشخصية، فإننا نوصي بشدة بتشغيله عبر HTTPS.
• أكمل التثبيت فور رفع الملفات. إلى أن يكتمل التثبيت، يستطيع أي شخص يعرف عنوان URL فتح المُثبِّت.
• إذا كنت تستخدم Nginx، فأجرِ مسبقًا الإعدادات الموضّحة في «إذا كنت تستخدم Nginx» أدناه.

خطوات التثبيت

1. 1ارفع ملفات GeckoFlag إلى خادمك عبر FTP/SFTP أو لوحة تحكم الاستضافة، ثم استخرجها.
2. 2افتح المُثبِّت في متصفحك. سيتحقق من بيئة الخادم — إصدار PHP، والإضافات المطلوبة، وأذونات المجلدات — ويعرض قائمة تحقق.
3. 3أدخل تفاصيل الاتصال بقاعدة البيانات (المضيف، والمنفذ، واسم قاعدة البيانات، واسم المستخدم، وكلمة المرور) ثم تابع.
4. 4انقر على تشغيل لتهيئة قاعدة البيانات — سيؤدي ذلك إلى إنشاء الجداول التي يحتاجها GeckoFlag.
5. 5أنشئ حساب المسؤول باسم وبريد إلكتروني وكلمة مرور.
6. 6أدخل مفتاح الترخيص للتحقق منه.
7. 7بمجرد التحقق من ترخيصك، يصبح كل شيء جاهزًا — سجّل الدخول بحساب المسؤول الجديد وابدأ في إعداد مشاريعك.

إذا كنت تستخدم Nginx

في Apache، يرفض ملف .htaccess المرفق مع GeckoFlag تلقائيًا الوصول المباشر إلى ملفات الإعدادات والسجلات وغيرها. أما Nginx فلا يستخدم .htaccess، لذا أضف المحتوى التالي إلى إعدادات الخادم. وإن لم تفعل، فقد تصبح ملفات الإعدادات والملفات المرفوعة مكشوفة من الخارج.

في خوادم الاستضافة التي تجمع بين Nginx وApache (حيث يستقبل Nginx الطلبات ويعالجها Apache)، يكون .htaccess فعّالًا، لذا لا حاجة إلى هذه الإعدادات. تحقّق من إمكانية استخدام .htaccess في دليل شركة الاستضافة التي تتعامل معها.

• اجعل المجلد العام (جذر المستندات) هو المجلد webroot الموجود داخل مجلد GeckoFlag، لا مجلد GeckoFlag نفسه.
• عدّل server_name (النطاق) وroot (مكان وضع GeckoFlag) وfastcgi_pass (وجهة الاتصال بـ PHP-FPM) بما يناسب بيئتك.
• أضف إعدادات HTTPS (listen 443 ssl وتحديد الشهادة) وفقًا لطريقة الإعداد المتّبعة في بيئتك.

server {
    listen 80;
    server_name pm.example.com;

    # المجلد العام (جذر المستندات) هو مجلد webroot الخاص بـ GeckoFlag
    root /var/www/geckoflag/webroot;
    index index.php;

    # عدم عرض قائمة محتويات المجلدات
    autoindex off;

    # للسماح برفع ملفات ZIP الخاصة بالتحديث والنسخ الاحتياطي
    # (القيمة الافتراضية في Nginx هي 1MB). اضبط upload_max_filesize
    # و post_max_size في PHP على القيمة نفسها أو أكبر
    client_max_body_size 100m;

    # عدم تقديم الملفات المخفية (.htaccess و .git وغيرها)
    location ~ /\.(?!well-known/) {
        deny all;
    }

    # عدم تقديم أي شيء سوى الصور من مجلدات الصور المرفوعة
    location ~ ^/img/(avatars|project_thumbnails|branding)/ {
        location ~* \.(jpe?g|jfif|png|gif|webp|ico)$ {
            add_header X-Content-Type-Options "nosniff" always;
            try_files $uri =404;
        }
        # صور SVG للعرض فقط (دون السماح بتنفيذ النصوص البرمجية)
        location ~* \.svg$ {
            add_header X-Content-Type-Options "nosniff" always;
            add_header Content-Security-Policy "default-src 'none'; img-src data:; style-src 'unsafe-inline'; sandbox" always;
            try_files $uri =404;
        }
        return 403;
    }

    # عدم تقديم مجلد files مباشرةً
    location ^~ /files/ {
        return 404;
    }

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    # لا يُنفَّذ كـ PHP سوى index.php
    location = /index.php {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root/index.php;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }
    location ~ \.php$ {
        return 404;
    }
}

بعد تغيير الإعدادات، تحقّق من صحة الصياغة باستخدام nginx -t ثم أعد تحميل Nginx.