Hướng dẫn deploy Laravel lên Coolify từ local lên server với CI/CD cơ bản

Nếu đang có một dự án Laravel chạy tốt ở máy local và muốn đưa nó lên server để truy cập qua Internet, Coolify là một lựa chọn khá dễ tiếp cận. Điểm hay của Coolify là có giao diện quản trị trực quan, hỗ trợ lấy source từ GitHub, tự build, tự deploy và có thể thiết lập webhook để mỗi lần push code là ứng dụng được cập nhật lại gần như theo mô hình CI/CD cơ bản.

Thay vì để Coolify tự nhận diện stack và build bằng Nixpacks, bài viết này chọn cách dùng Dockerfile. Với Laravel, đây là cách dễ kiểm soát hơn vì có thể chủ động quyết định phiên bản PHP, extension cần cài, cách copy source, cách chạy migrate và cách khởi động container. Khi làm tutorial cho người mới, việc nhìn thấy mọi thứ nằm rõ trong Dockerfile cũng dễ hiểu hơn việc để hệ thống tự đoán.

Bắt đầu từ project Laravel ở local

Project dùng trong bài là một ứng dụng Laravel mẫu. Ở local, source code nằm trong thư mục laravel-coolify-demo. Trong file composer.json có thể thấy dự án đang dùng Laravel 13 và yêu cầu PHP từ 8.3 trở lên. Đó là thông tin quan trọng vì khi lên server, môi trường runtime cũng phải đáp ứng tương ứng.

Phần build được định nghĩa sẵn trong Dockerfile của project. Dockerfile này chia thành hai stage. Stage đầu dùng image composer:2 để chạy composer install --no-dev --optimize-autoloader, giúp cài dependency gọn hơn cho môi trường production. Stage thứ hai dùng php:8.4-apache, cài thêm các package cần thiết như sqlite3, pdo_sqlite, bật mod_rewrite cho Apache và chỉnh document root trỏ về thư mục public của Laravel.

Ngoài Dockerfile, project còn có script khởi động container để xử lý những việc thường gặp khi deploy Laravel: cập nhật lại giá trị trong file .env theo biến môi trường thực tế, đặt APP_ENV=production, tắt APP_DEBUG, cấu hình APP_URL, dùng SQLite cho demo, chạy php artisan migrate --force và tối ưu cache. Với bài hướng dẫn nhập môn, cách làm này khá phù hợp vì người đọc không phải cấu hình quá nhiều thành phần ngay từ đầu.

Trước khi đưa lên Coolify, source đã được đẩy lên GitHub dưới dạng public repository. Đây là bước cần thiết vì Coolify sẽ lấy source trực tiếp từ repository đó để build. Nếu đang làm với repository private, vẫn có thể triển khai bằng cách kết nối Git provider hoặc cấu hình access token phù hợp. Tuy nhiên để bài viết dễ theo dõi và ít phát sinh lỗi xác thực, phần demo dùng repo public.

Tạo application mới trên Coolify

Sau khi đăng nhập vào giao diện Coolify, bước đầu tiên là tạo resource mới cho ứng dụng. Đây là nơi khai báo application sẽ được build từ đâu, chạy trên server nào và publish qua domain nào. Trong case thực tế này, ứng dụng được đặt tên là Laravel Coolify Demo. vào Dasboard => Projects, tạo mới hoặc chọn project sẵn có.

Ở đây sẽ chọn ứng dụng kiểu Git Based với tuỳ chọn Public Repository hoặc Private Repository tuỳ theo nhu cầu của bạn. Nếu dùng repository private, bạn cần kết nối tài khoản GitHub vào Coolify trước để hệ thống có quyền đọc source. Phần này mình đã hướng dẫn riêng trong bài CI/CD trên Coolify – Tích hợp GitHub, GitLab, Bitbucket, nhất là bước kết nối Git provider trước khi tạo application.

Sau khi chọn tạo application, Coolify sẽ yêu cầu khai báo source code. Với repository public, chỉ cần nhập URL GitHub là đủ.

Branch được dùng để deploy là branch chính của project. Khi nhập xong, Coolify sẽ kiểm tra repository để xác định có thể clone source hay không.

Ở bước chọn build pack hoặc strategy, thay vì để Coolify tự phát hiện bằng Nixpacks, bài này chủ động chọn Dockerfile. Cái này cũng phụ thuộc vào thiết kế dự án ban đầu của bạn nữa.

Với nhiều ứng dụng PHP nói chung và Laravel nói riêng, Nixpacks có thể build được, nhưng kết quả phụ thuộc khá nhiều vào việc source đang có cấu trúc như thế nào, cần extension PHP nào, có frontend build hay không, web server chạy bằng gì và command start cần viết ra sao. Khi dùng Dockerfile, toàn bộ logic build đều nằm trong source code nên dễ dự đoán, dễ sửa và dễ tái sử dụng ở các môi trường khác.

Sau khi source đã được nhận diện và chiến lược build đã rõ ràng, Coolify sẽ tạo trang cấu hình application. Tại đây có thể chỉnh tên app, branch, build context, port nội bộ của container, URL public và một số tùy chọn deploy khác. Với Dockerfile trong project này, container sẽ expose cổng 80 nên application trên Coolify cũng cần map đúng cổng đó.

Khai báo cấu hình cần thiết trước lần deploy đầu tiên

Với Laravel, ngoài source code thì phần biến môi trường cũng rất quan trọng. Trong project demo, script khởi động container đã xử lý sẵn một số giá trị cơ bản như APP_ENV, APP_DEBUG, APP_URL và cấu hình database SQLite. Tuy vậy, trên Coolify vẫn nên kiểm tra lại các biến quan trọng trước khi bấm deploy lần đầu.

Ít nhất nên bảo đảm có APP_KEY hợp lệ, APP_ENV=production, APP_DEBUG=false và APP_URL đúng với domain hoặc URL public sẽ dùng để truy cập website. Nếu ứng dụng dùng MySQL hoặc PostgreSQL thay vì SQLite, đây cũng là lúc khai báo các biến như DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME và DB_PASSWORD. Bài demo dùng SQLite để giữ quy trình đơn giản, nhưng khi làm project thực tế hơn, thường sẽ kết hợp Laravel application với database service riêng.

Nếu mới làm quen với Laravel, có thể hiểu ngắn gọn là Coolify không thay thế file .env theo kiểu sửa source trước khi commit. Thay vào đó, các biến môi trường được đưa vào lúc container chạy. Dockerfile và script start sẽ đọc những biến này để cấu hình ứng dụng cho môi trường production. Cách làm này an toàn và phù hợp hơn so với việc đẩy file .env thật lên GitHub.

Deploy ứng dụng từ GitHub lên Coolify

Khi đã lưu cấu hình xong, có thể bấm deploy hoặc redeploy để Coolify bắt đầu quá trình build image từ source GitHub. Ở phía sau, Coolify sẽ clone repository, đọc Dockerfile, build image theo các bước đã khai báo rồi chạy container mới trên server được chọn. Nếu có lỗi ở bước nào, hệ thống sẽ hiển thị trong phần logs để kiểm tra.

Với project demo này, quá trình deploy thành công và application chuyển sang trạng thái running. Sau khi container khởi động, script start đã tự chạy migration, tối ưu cache và đưa Apache lên foreground để giữ container hoạt động. Đây là lý do bài viết ưu tiên Dockerfile: mọi việc quan trọng sau build đều có thể kiểm soát trong source thay vì phụ thuộc vào suy đoán của platform.

Trong giao diện application, tab Deployments giúp theo dõi lịch sử các lần deploy, biết lần nào thành công, lần nào thất bại và được thực hiện từ commit hoặc branch nào. Khi cần kiểm tra sâu hơn, tab Logs sẽ cho thấy log build và log runtime. Đây là nơi nên xem đầu tiên nếu ứng dụng không lên, báo lỗi extension PHP, thiếu package Composer, sai biến môi trường hoặc lỗi permission.

CI/CD tự động từ GitHub lên Coolify hoạt động như thế nào

Sau khi deploy thủ công thành công một lần, bước tiếp theo nên hiểu là cách tự động hóa. Trong mô hình đơn giản nhất, developer làm việc trên local, commit thay đổi rồi push lên GitHub. Khi repository có commit mới trên branch đã khai báo, Coolify có thể nhận tín hiệu và tự chạy lại quy trình deploy. Như vậy, GitHub đóng vai trò nơi lưu source, còn Coolify nhận source đó để build và phát hành ứng dụng mới.

Để cơ chế này chạy ổn định, cần chú ý hai phần. Thứ nhất là application trên Coolify phải được cấu hình đúng repository và branch. Thứ hai là webhook hoặc tính năng auto deploy phải được bật đúng cách để mỗi lần có thay đổi, Coolify biết lúc nào cần khởi động lại pipeline build. Trong giao diện application của Coolify thường có tab Webhooks để cung cấp endpoint nhận thông báo từ GitHub hoặc cho phép kiểm tra trạng thái thiết lập hiện tại.

Với repository public như trong bài demo, quy trình dễ hình dung như sau: chỉnh sửa code ở local, push lên GitHub repository laravel-coolify-demo, GitHub gửi tín hiệu qua webhook hoặc Coolify phát hiện có thay đổi ở branch theo cấu hình, sau đó Coolify tự clone version mới nhất và build lại bằng Dockerfile. Nếu build thành công, phiên bản mới sẽ được thay vào phiên bản đang chạy. Đây chính là mô hình CI/CD ở mức cơ bản nhưng rất hữu ích cho các website và ứng dụng nhỏ hoặc môi trường thử nghiệm.

Khi đã quen hơn, có thể mở rộng workflow này bằng cách chia branch rõ ràng hơn, ví dụ chỉ deploy branch main cho production, còn branch khác dùng cho staging. Nhưng ở mức nhập môn, chỉ cần hiểu rằng GitHub là nơi giữ source và lịch sử commit, còn Coolify là nơi build, chạy và publish ứng dụng. Mỗi lần source đổi, deploy cũng có thể được tự động hóa thay vì làm tay từ đầu.

Cấu hình domain

Sau khi application chạy thành công, Coolify có thể cung cấp một URL tạm để kiểm tra nhanh. Ở đây, URL public đang hoạt động là http://t11dhl6xxxx.IP-SERVER.sslip.io. Đây là cách rất tiện để xác minh ứng dụng đã lên được trước khi cấu hình domain chính thức.

Nếu cần sử dụng domain riêng cho dự án thì thay đổi cấu hình ở phần domain và sau đó thực hiện trỏ domain về địa chỉ IP của máy chủ Coolifyy.

Kết bài

Trong quá trình làm bài này có gặp một lỗi thực tế khá phổ biến với Laravel: ứng dụng trả về HTTP 500 do thiếu APP_KEY. Với Coolify, bạn nên kiểm tra lại phần Environment Variables nếu ứng dụng build xong nhưng truy cập vẫn lỗi. Đây cũng là lý do bài viết này dành một bước riêng cho việc rà biến môi trường trước và sau lần deploy đầu tiên.

Với quy trình trên, project Laravel từ local đã được đưa lên GitHub, kết nối vào Coolify, build bằng Dockerfile và chạy thành công trên server. Ứng dụng hiện có thể truy cập công khai qua URL kiểm tra, trạng thái application trên Coolify là running, lịch sử deployments và logs đều có thể theo dõi trực tiếp từ dashboard. Đây là một quy trình khá phù hợp để bắt đầu làm quen với việc đưa Laravel từ máy cá nhân lên môi trường thực tế.

Nếu đang cần một máy chủ để cài Coolify và tự triển khai các ứng dụng Laravel, có thể tham khảo các gói Pro VPS, X-Platinum VPS hoặc AMD Cloud Server tại AZDIGI. Với nhu cầu học tập, thử nghiệm hoặc chạy project nhỏ, các gói VPS/Cloud ở phân khúc thấp đã đủ để bắt đầu. Khi ứng dụng cần tài nguyên ổn định hơn hoặc chạy thêm nhiều service đi kèm, có thể nâng cấp dần theo nhu cầu thực tế.

Trong trường hợp muốn đi xa hơn, có thể tiếp tục hoàn thiện quy trình bằng cách tách database ra service riêng, cấu hình backup phù hợp, dùng SSL cho domain chính thức và bổ sung staging environment trước khi deploy production. Nhưng ngay ở mức cơ bản, triển khai Laravel lên Coolify bằng GitHub và Dockerfile đã là một bước rất thực tế để chuyển từ môi trường local sang môi trường chạy thật.