Hướng dẫn

GeckoFlag là phần mềm tự lưu trữ mà bạn cài đặt trên máy chủ của riêng mình — một trình cài đặt chuyên dụng sẽ hướng dẫn bạn qua từng bước để ai cũng có thể thiết lập dễ dàng.

Trước khi bắt đầu

• Xác nhận máy chủ của bạn đáp ứng yêu cầu hệ thống. Không cần Composer — gói phân phối đã bao gồm sẵn các thư viện phụ thuộc (thư mục vendor), nên cũng chạy được trong môi trường không thể chạy Composer.
• Hãy chuẩn bị sẵn thông tin kết nối cơ sở dữ liệu: một cơ sở dữ liệu mới, hoặc một cơ sở dữ liệu trống đã có. Chúng tôi không khuyến nghị dùng chung cơ sở dữ liệu với ứng dụng khác.
• HTTPS không bắt buộc, nhưng vì GeckoFlag xử lý thông tin đăng nhập và dữ liệu cá nhân nên chúng tôi rất khuyến nghị chạy qua HTTPS.
• Sau khi tải tệp lên, hãy hoàn tất cài đặt ngay. Cho đến khi cài đặt xong, bất kỳ ai biết URL đều có thể mở trình cài đặt.
• Nếu bạn dùng Nginx, hãy thực hiện trước phần thiết lập trong mục “Nếu bạn dùng Nginx” bên dưới.

Các bước cài đặt

1. 1Tải các tệp GeckoFlag lên máy chủ của bạn qua FTP/SFTP hoặc bảng điều khiển hosting, rồi giải nén.
2. 2Mở trình cài đặt trong trình duyệt của bạn. Nó kiểm tra môi trường máy chủ — phiên bản PHP, các tiện ích mở rộng bắt buộc và quyền thư mục — và hiển thị danh sách kiểm tra.
3. 3Nhập thông tin kết nối cơ sở dữ liệu (host, cổng, tên cơ sở dữ liệu, tên người dùng và mật khẩu) rồi tiếp tục.
4. 4Nhấp Chạy để khởi tạo cơ sở dữ liệu — thao tác này tạo các bảng mà GeckoFlag cần.
5. 5Tạo tài khoản quản trị viên với tên, email và mật khẩu.
6. 6Nhập khóa giấy phép của bạn để xác minh.
7. 7Khi giấy phép được xác minh, mọi thứ đã sẵn sàng — đăng nhập bằng tài khoản quản trị viên mới và bắt đầu thiết lập các dự án.

Nếu bạn dùng Nginx

Với Apache, tệp .htaccess đi kèm GeckoFlag sẽ tự động chặn truy cập trực tiếp vào tệp cấu hình, nhật ký và các tệp tương tự. Nginx không sử dụng .htaccess, vì vậy hãy thêm nội dung sau vào cấu hình máy chủ. Nếu không thêm, tệp cấu hình và các tệp đã tải lên có thể bị nhìn thấy từ bên ngoài.

Trên các gói hosting kết hợp Nginx và Apache (cấu hình trong đó Apache xử lý các yêu cầu do Nginx tiếp nhận), .htaccess vẫn có hiệu lực nên không cần thiết lập này. Hãy kiểm tra trong tài liệu hướng dẫn của nhà cung cấp hosting xem có dùng được .htaccess hay không.

• Hãy đặt thư mục công khai (document root) là thư mục webroot bên trong thư mục GeckoFlag, chứ không phải chính thư mục GeckoFlag.
• Hãy sửa server_name (tên miền), root (nơi đặt GeckoFlag) và fastcgi_pass (địa chỉ kết nối PHP-FPM) cho phù hợp với môi trường của bạn.
• Hãy thêm thiết lập HTTPS (listen 443 ssl và chỉ định chứng chỉ) theo cách thiết lập của môi trường bạn đang dùng.

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

    # Thư mục công khai (document root) là thư mục webroot của GeckoFlag
    root /var/www/geckoflag/webroot;
    index index.php;

    # Không hiển thị danh sách nội dung thư mục
    autoindex off;

    # Để có thể tải lên tệp ZIP cập nhật và sao lưu
    # (giá trị mặc định của Nginx là 1MB). Hãy đặt upload_max_filesize và
    # post_max_size của PHP bằng hoặc lớn hơn giá trị này
    client_max_body_size 100m;

    # Không phục vụ các tệp ẩn (.htaccess, .git, v.v.)
    location ~ /\.(?!well-known/) {
        deny all;
    }

    # Chỉ phục vụ tệp hình ảnh từ các thư mục chứa hình ảnh đã tải lên
    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;
        }
        # Hình ảnh SVG chỉ để hiển thị (không cho chạy tập lệnh)
        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;
    }

    # Không phục vụ trực tiếp thư mục files
    location ^~ /files/ {
        return 404;
    }

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

    # Chỉ index.php được thực thi như 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;
    }
}

Sau khi thay đổi cấu hình, hãy kiểm tra cú pháp bằng nginx -t rồi tải lại Nginx.