Ứng dụng Ruby và Rails

Cài Ruby, deploy Rails, Sinatra hay ứng dụng Rack khác từ Git với Bundler và Puma, precompile asset, kết nối database và đặt biến môi trường.

Cập nhật 09/10/2026 · 7 phút đọc

Ứng dụng Ruby chạy trên ZoPanel như ứng dụng server: ZoPanel cài gem bằng Bundler, build bản release, chạy ứng dụng như một dịch vụ của tài khoản hosting phía sau nginx và chuyển sang bản mới không gián đoạn. Trang này dành cho Ruby on Rails, ứng dụng Rack (Sinatra, Hanami…) và server Ruby thuần; cổng, phát hành blue/green và log hoạt động như mô tả trong Ứng dụng Node.js và Python.

Cài Ruby lên máy chủ

Quản trị viên cài Ruby một lần:

1. Mở Runtime.
2. Trong thẻ Ruby ("Ruby kèm Bundler, cho Rails và Sinatra."), bấm Cài đặt.

ZoPanel cài Ruby của hệ điều hành kèm Bundler và các thư viện mà gem native cần:

ruby-full ruby-bundler build-essential libyaml-dev zlib1g-dev libssl-dev
libpq-dev libsqlite3-dev default-libmysqlclient-dev pkg-config

Nhờ vậy các gem như pg, mysql2, sqlite3, psych, nokogiri biên dịch được mà không cần thêm bước nào. Sau khi cài, thẻ hiển thị phiên bản Ruby.

Mỗi máy chủ có một bản Ruby, chính là bản hệ điều hành cung cấp:

Rails 8.0 cần Ruby 3.2 trở lên, Rails 7.2 cần Ruby 3.1 trở lên (hướng dẫn nâng cấp Rails). Dòng ruby "x.y" trong Gemfile phải khớp Ruby của máy chủ, nếu không Bundler sẽ dừng. Ô Phiên bản và Gemfile không chọn được Ruby khác. Mọi log build đều bắt đầu bằng Ruby đang dùng, ví dụ "Using the system Ruby 3.2.3", và thêm cảnh báo khi Gemfile yêu cầu phiên bản khác. Nếu ứng dụng cần phiên bản Ruby khác, hãy deploy bằng Dockerfile (xem Deploy bằng Docker).

Deploy

1. Ở Website → Thêm website, chọn Git deploy, nhập Địa chỉ repository, Nhánh (và Thư mục gốc với monorepo) rồi bấm Tạo website. Với website có sẵn, dùng tab Deploy.
2. ZoPanel nhận diện Ruby qua Gemfile và đề xuất các lệnh bên dưới.
3. Khai báo cấu hình trong Biến môi trường rồi bấm Lưu & deploy lại.

Lệnh được nhận diện

Mọi ứng dụng Ruby dùng chung lệnh cài đặt. Gem được cài vào bản release (vendor/bundle), không cài cho toàn hệ thống, và bỏ qua nhóm development, test:

bundle config set --local path vendor/bundle && bundle config set --local without 'development test' && bundle install --jobs 4

Với Rails, Đường dẫn lưu trữ cố định được đặt là storage và log, log deploy ghi chú "Set SECRET_KEY_BASE and DATABASE_URL in the environment variables". Dòng web: trong Procfile luôn được ưu tiên làm lệnh chạy.

Muốn đổi lệnh, tắt Tự nhận diện trong thẻ Build & chạy, sửa rồi bấm Lưu & deploy.

Puma

rails server khởi động Puma, server mặc định của ứng dụng Rails mới (gem "puma" trong Gemfile). Tuỳ chọn -b và -p gắn Puma vào 127.0.0.1:$PORT. Số thread lấy từ config/puma.rb (RAILS_MAX_THREADS, mặc định 3 ở Rails 8). Muốn chạy Puma trực tiếp, có thể dùng:

bundle exec puma -C config/puma.rb -b tcp://127.0.0.1:$PORT -e production

Với ứng dụng Rack dùng Rack 3 (Sinatra 4 trở lên), lệnh rackup nằm trong gem riêng: thêm gem "rackup" và gem "puma" vào Gemfile (README của Sinatra).

Biến môi trường

Đặt các biến sau trong Biến môi trường ở tab Deploy. Chúng dùng được khi build và khi chạy; PORT được đặt tự động.

Lệnh build chỉ đặt SECRET_KEY_BASE giả cho bước assets:precompile, nên bước precompile không cần khoá thật.

Database

SQLite (mặc định của Rails 8). Ứng dụng Rails 8 mới lưu database production trong storage/ (storage/production.sqlite3 cùng các database cache, queue, cable). storage là đường dẫn lưu trữ cố định nên dữ liệu được giữ qua mọi lần deploy. Ngoài migration, không cần làm gì thêm.

MariaDB hoặc PostgreSQL. Tạo database ở Cơ sở dữ liệu rồi đặt DATABASE_URL; host là 127.0.0.1 (cấu hình database của Rails):

# MariaDB với gem mysql2
DATABASE_URL=mysql2://alice_app:mat-khau@127.0.0.1:3306/alice_app
# MariaDB với gem trilogy (Rails 7.1+)
DATABASE_URL=trilogy://alice_app:mat-khau@127.0.0.1:3306/alice_app
# PostgreSQL với gem pg
DATABASE_URL=postgresql://alice_app:mat-khau@127.0.0.1:5432/alice_app

Mã hoá URL các ký tự đặc biệt trong mật khẩu (ví dụ @ thành %40).

Migration

Migration không tự chạy. Tắt Tự nhận diện rồi thêm vào cuối lệnh build:

RAILS_ENV=production SECRET_KEY_BASE=precompile bundle exec rails assets:precompile && RAILS_ENV=production bundle exec rails db:prepare

db:prepare tạo database còn thiếu và chạy các migration đang chờ. Bước build chạy trước khi bản mới được đưa lên, trong lúc bản cũ vẫn phục vụ khách, nên hãy viết migration sao cho bản đang chạy vẫn hoạt động được.

SSL, file tĩnh và file tải lên

• nginx xử lý SSL và gửi header X-Forwarded-Proto. Rails 8 bật config.assume_ssl và config.force_ssl ở production, Rails 7.1 bật config.force_ssl: hãy giữ SSL miễn phí (Let's Encrypt), nếu không cookie bảo mật và chuyển hướng sẽ làm hỏng đăng nhập qua HTTP thường.
• nginx chuyển mọi request tới ứng dụng, kể cả file trong public/. Từ Rails 7.1, Rails tự phục vụ các file này; với Rails 7.0 hãy đặt RAILS_SERVE_STATIC_FILES=1.
• Active Storage dùng disk local sẽ ghi vào storage/, vốn là đường dẫn lưu trữ cố định. Thư mục khác cần giữ lại giữa các bản, ví dụ public/uploads, hãy thêm vào Đường dẫn lưu trữ cố định.

Release, log và khởi động lại

• Bản mới khởi động ở slot đang rảnh và phải trả lời Đường dẫn health check (mặc định /) với mã dưới 500 trong vòng 90 giây; chuyển hướng vẫn tính là đạt. Từ Rails 7.1 có sẵn route /up để dùng làm health check. Chỉ khi đó nginx mới chuyển sang và tiến trình cũ mới dừng.
• Các bản release giữ 5 bản build gần nhất để Rollback (database không được rollback).
• Log ứng dụng hiển thị 400 dòng cuối ứng dụng ghi ra; bật Trực tiếp để theo dõi. Thư mục log/ cũng được lưu trữ cố định.
• Dịch vụ tự khởi động lại khi Puma thoát. RAM và CPU được tính vào gói của tài khoản.

Xử lý sự cố

Xem thêm

• Ứng dụng Node.js và Python
• Git deploy
• Cơ sở dữ liệu
• Chứng chỉ SSL
• Rails guides