Tự cài đặt (self-host)

Chạy The Collective trên máy chủ của bạn bằng Docker. Dữ liệu nằm hoàn toàn trong hạ tầng của bạn.

Yêu cầu

• Máy chủ Linux x64, tối thiểu 2 CPU, 4 GB RAM, 20 GB ổ đĩa.
• Docker Engine và Docker Compose v2.
• Một tên miền trỏ về máy chủ, nginx trên máy chủ để giữ HTTPS.
• Tài khoản SMTP để gửi email (xác minh tài khoản, quên mật khẩu).

Thành phần

Stack gồm các container: ứng dụng PHP, nginx, worker hàng đợi, scheduler, Reverb (realtime), MySQL, Redis và phpMyAdmin (tuỳ chọn). Chỉ nginx (cổng 18000), Reverb (18002) và phpMyAdmin (18001) mở ra 127.0.0.1 để nginx của máy chủ chuyển tiếp vào; MySQL và Redis không mở cổng ra ngoài.

1. Lấy mã nguồn

git clone [ĐIỀN: URL repository] the-collective
cd the-collective

2. Cấu hình

cp .env.production.example .env
chmod 600 .env

Điền mọi giá trị CHANGE_ME trong .env:

Lưu ý: các biến VITE_* được nhúng vào giao diện lúc build. Đổi chúng thì phải build lại image.

3. Build và khởi động

docker compose -f compose.prod.yaml build
docker compose -f compose.prod.yaml run --rm -u www-data app php artisan passport:keys --no-interaction
docker compose -f compose.prod.yaml run --rm -u www-data app php artisan migrate --force
docker compose -f compose.prod.yaml up -d
docker compose -f compose.prod.yaml exec -u www-data app php artisan db:seed --class=RequireSeeder --force

Lệnh db:seed chỉ chạy một lần ở lần cài đầu tiên, để nạp danh mục bắt buộc (vai trò, quyền, trạng thái, độ ưu tiên).

Kiểm tra: curl -fsS http://127.0.0.1:18000/up phải trả về thành công.

4. Nginx và HTTPS trên máy chủ

Mã nguồn có sẵn file mẫu docker/nginx/vps.conf:

sudo cp docker/nginx/vps.conf /etc/nginx/sites-available/the-collective.conf
sudo sed -i 's/<ten-mien>/ten-mien-cua-ban.com/g' /etc/nginx/sites-available/the-collective.conf
sudo ln -s /etc/nginx/sites-available/the-collective.conf /etc/nginx/sites-enabled/

Cấp chứng chỉ HTTPS (Let's Encrypt), rồi tạo mật khẩu bảo vệ phpMyAdmin:

sudo apt install -y certbot apache2-utils
sudo mkdir -p /var/www/letsencrypt
sudo certbot certonly --webroot -w /var/www/letsencrypt -d ten-mien-cua-ban.com
sudo htpasswd -c /etc/nginx/.htpasswd-phpmyadmin <tên-đăng-nhập>
sudo chown root:www-data /etc/nginx/.htpasswd-phpmyadmin
sudo chmod 640 /etc/nginx/.htpasswd-phpmyadmin
sudo nginx -t && sudo systemctl reload nginx

Lưu ý: khối server cổng 443 trong file mẫu tham chiếu tới chứng chỉ. Nếu nginx -t báo thiếu chứng chỉ ở lần đầu, tạm tắt khối 443, cấp chứng chỉ qua khối cổng 80 rồi bật lại.

File mẫu đã ẩn phiên bản phần mềm, chặn các đường dẫn hay bị dò quét và có sẵn hai dòng (đang tắt) để khoá cả site bằng mật khẩu trong giai đoạn thử nghiệm.

5. Cập nhật phiên bản mới

git pull
docker compose -f compose.prod.yaml build
docker compose -f compose.prod.yaml run --rm -u www-data app php artisan migrate --force
docker compose -f compose.prod.yaml up -d --remove-orphans

Xem có gì mới ở trang Phiên bản trước khi cập nhật.

6. Sao lưu

Dữ liệu cần sao lưu định kỳ: database và volume storage (file tải lên, khoá OAuth).

# Database
docker compose -f compose.prod.yaml exec -T mysql \
    mysqldump -u root -p"$MYSQL_ROOT_PASSWORD" --single-transaction the_collective \
    | gzip > backup-$(date +%F).sql.gz

# File tải lên + khoá OAuth
docker run --rm -v the-collective-prod_storage:/data -v "$PWD":/backup alpine \
    tar czf /backup/storage-$(date +%F).tar.gz -C /data .

Lưu ý: mất volume storage thì mất khoá OAuth - mọi agent phải đăng nhập lại.