Hướng dẫn cài ERPNext lên VPS bằng Docker và FlashPanel

ERPNext là phần mềm quản trị doanh nghiệp mã nguồn mở, hỗ trợ quản lý khách hàng, bán hàng, mua hàng, kho, kế toán và dự án. Với doanh nghiệp nhỏ, tự triển khai ERPNext trên VPS là một cách chủ động quản lý hệ thống và dữ liệu.

Tuy nhiên, quá trình cài đặt dễ gặp lỗi nếu chọn nhầm image, nhập sai thông tin database hoặc tự build trên VPS có ít tài nguyên. Bài viết này hướng dẫn triển khai bằng image Docker có sẵn, kết hợp FlashPanel để quản lý tên miền và SSL.

Lưu ý phiên bản: ERPNext v16.53.0 là phiên bản cụ thể dùng trong hướng dẫn, không mặc định là phiên bản mới nhất khi bạn đọc bài. Thay erp.example.com bằng tên miền thật ở tất cả các lệnh.

Mục lục bài viết

1. Chuẩn bị VPS

Cấu hình tham khảo cho giai đoạn thử nghiệm và nhóm nhỏ:

RAM và dung lượng thực tế còn phụ thuộc số người dùng, dữ liệu, báo cáo và các ứng dụng khác cùng chạy trên VPS. VPS 4 GB RAM có thể dùng để thử nghiệm, nhưng cần theo dõi bộ nhớ. Swap hỗ trợ khi thiếu RAM, không thay thế được RAM vật lý.

Kiểm tra tài nguyên:

free -h
df -h /

Nếu VPS đã có website hoặc database quan trọng, hãy tạo snapshot trước khi bắt đầu.

2. Cài Docker và kiểm tra công cụ

Đăng ký FlashPanel và nhận ưu đãi

Trước khi cài đặt, hãy đăng ký tài khoản FlashPanel và kết nối VPS của bạn.

Đăng ký sử dụng miễn phí ngay tại đây!

1. Mở liên kết trên và tạo tài khoản FlashPanel.
2. Kết nối VPS với FlashPanel theo hướng dẫn trong tài khoản.
3. Nếu mua bản S5, S20 hoặc Pro Unlimited, nhập mã KZDIZS tại bước thanh toán để nhận giảm 10%. Kiểm tra số tiền được giảm trước khi thanh toán.
4. Sau khi kết nối máy chủ thành công, tiếp tục cài Docker theo hướng dẫn bên dưới.

Mã ưu đãi: KZDIZS
Giảm 10% khi mua bản S5, S20 hoặc Pro Unlimited. Điều kiện áp dụng và mức giảm thực tế được xác nhận tại trang thanh toán của FlashPanel. Đăng ký tài khoản FlashPanel không bao gồm chi phí thuê VPS.

Minh bạch liên kết: Đây là liên kết tiếp thị liên kết. Tôi có thể nhận hoa hồng khi bạn đăng ký và mua gói qua liên kết giới thiệu này.

Trong FlashPanel, mở phần Ứng dụng của máy chủ và cài Docker. Sau đó mở Terminal máy chủ, kiểm tra:

docker --version
docker compose version

Bài viết sử dụng Docker Compose v2 với cú pháp docker compose. Cài các công cụ hỗ trợ:

apt-get update
apt-get install -y git openssl curl

Các lệnh trong bài được chạy bằng tài khoản root. Sao chép nội dung bên trong khối lệnh, không thêm dấu nhắc root@server:~#.

3. Tải image ERPNext và kiểm tra ứng dụng

docker pull frappe/erpnext:v16.53.0

Kiểm tra nội dung image trước khi triển khai:

docker run --rm --pull=never --entrypoint ls   frappe/erpnext:v16.53.0   -1 /home/frappe/frappe-bench/apps

Kết quả cần có:

erpnext
frappe

Frappe là nền tảng, ERPNext là ứng dụng chạy trên nền tảng đó. Chỉ nhìn thấy giao diện Frappe chưa chứng minh ERPNext đã được cài.

Tham khảo repository ERPNext chính thức và Frappe Docker.

Cấu hình chạy nhanh bằng pwd.yml trong README được đánh dấu là môi trường demo dùng thử; triển khai lâu dài cần cấu hình phù hợp hơn.

4. Chuẩn bị cấu hình Docker

Tạo thư mục:

mkdir -p /opt/my-erp
chmod 700 /opt/my-erp
cd /opt/my-erp

Tải repository Docker của Frappe:

git clone --depth 1 \
  https://github.com/frappe/frappe_docker.git

Ghi nhận phiên bản repository để tiện đối chiếu khi bảo trì:

git -C /opt/my-erp/frappe_docker rev-parse HEAD \
  > /opt/my-erp/docker-source-commit.txt

Tạo file cấu hình. Thay tên miền trước khi chạy:

umask 077

cat > /opt/my-erp/stack.env <<EOF
CUSTOM_IMAGE=frappe/erpnext
CUSTOM_TAG=v16.53.0
ERPNEXT_VERSION=v16.53.0
PULL_POLICY=missing
RESTART_POLICY=unless-stopped
DB_PASSWORD=$(openssl rand -hex 24)
FRAPPE_SITE_NAME_HEADER=erp.example.com
GUNICORN_WORKERS=1
GUNICORN_THREADS=2
EOF

File này tự sinh mật khẩu database và giới hạn số worker web ở mức khởi điểm cho VPS nhỏ.

Chỉ tạo file mật khẩu một lần. Khi database đã được khởi tạo, không chạy lại khối trên tùy tiện vì mật khẩu trong file có thể khác mật khẩu database đang lưu.

Tạo cấu hình cổng và database:

cat > /opt/my-erp/local.yaml <<'EOF'
services:
  frontend:
    ports:
      - "127.0.0.1:18081:8080"

  db:
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
      - --innodb-buffer-pool-size=256M
      - --max-connections=50
EOF

Cổng 18081 chỉ lắng nghe trên localhost. Người dùng truy cập qua tên miền và HTTPS do FlashPanel quản lý.

Sinh file Compose hoàn chỉnh:

docker compose   --project-name my_erp   --env-file /opt/my-erp/stack.env   -f /opt/my-erp/frappe_docker/compose.yaml   -f /opt/my-erp/frappe_docker/overrides/compose.mariadb.yaml   -f /opt/my-erp/frappe_docker/overrides/compose.redis.yaml   -f /opt/my-erp/local.yaml   config > /opt/my-erp/compose.yaml

Bảo vệ các file chứa mật khẩu:

chmod 600 /opt/my-erp/stack.env
chmod 600 /opt/my-erp/compose.yaml

Repository Docker có thể thay đổi theo thời gian. Nếu bước sinh cấu hình báo lỗi, hãy xử lý lỗi trước khi khởi động; không dùng file cấu hình tạo dở.

5. Khởi động hệ thống

Kiểm tra cú pháp:

docker compose -p my_erp   -f /opt/my-erp/compose.yaml config --quiet

Nếu không có lỗi, khởi động:

docker compose -p my_erp   -f /opt/my-erp/compose.yaml up -d

Kiểm tra trạng thái:

docker compose -p my_erp   -f /opt/my-erp/compose.yaml ps -a

Các dịch vụ chính gồm database, Redis, backend, frontend, WebSocket, scheduler và các worker xử lý tác vụ nền.

Container configurator chạy cấu hình rồi kết thúc. Nếu nó dừng với mã 0, đó là trạng thái bình thường; không cần xóa để tiết kiệm RAM.

Xem log cấu hình:

docker compose -p my_erp   -f /opt/my-erp/compose.yaml   logs --tail=80 configurator

Chỉ tạo site khi database đã khỏe và configurator hoàn tất thành công.

6. Tạo site và cài ERPNext

Xem mật khẩu database trên Terminal:

grep '^DB_PASSWORD=' /opt/my-erp/stack.env

Không chia sẻ mật khẩu hoặc chụp màn hình chứa mật khẩu lên các nhóm hỗ trợ.

Tạo site:

docker compose -p my_erp   -f /opt/my-erp/compose.yaml   exec backend bench new-site erp.example.com   --mariadb-user-host-login-scope='%'   --install-app erpnext

Khi nhập mật khẩu, Terminal thường không hiện ký tự. Đây là hành vi bình thường. Đợi quá trình cài Frappe và ERPNext hoàn tất, sau đó kiểm tra:

docker compose -p my_erp   -f /opt/my-erp/compose.yaml   exec -T backend bench --site erp.example.com list-apps

Kết quả cần có cả frappe và erpnext.

Nếu báo site đã tồn tại sau một lần cài lỗi, đừng thêm --force ngay. Site có thể đã được tạo một phần và cần kiểm tra trước khi sửa.

7. Thiết lập URL và scheduler

Đặt URL chính thức:

docker compose -p my_erp   -f /opt/my-erp/compose.yaml   exec -T backend bench --site erp.example.com   set-config host_name https://erp.example.com

Bật scheduler:

docker compose -p my_erp   -f /opt/my-erp/compose.yaml   exec -T backend bench --site erp.example.com   enable-scheduler

Xóa cache:

docker compose -p my_erp   -f /opt/my-erp/compose.yaml   exec -T backend bench --site erp.example.com clear-cache

Kiểm tra ứng dụng bên trong VPS:

curl -I --max-time 15   -H 'Host: erp.example.com'   http://127.0.0.1:18081/app

Phản hồi 200 hoặc chuyển hướng hợp lệ là tín hiệu ứng dụng đã trả lời. Trên bản v16 sử dụng trong quá trình triển khai này, /app chuyển hướng sang /desk.

8. Kết nối tên miền qua FlashPanel

Trong DNS, tạo bản ghi:

Trong FlashPanel, tạo website:

FlashPanel hỗ trợ trường Proxy Port để chuyển truy cập từ tên miền tới ứng dụng chạy ở cổng nội bộ. Xem hướng dẫn tạo và quản lý website.

Trong cấu hình proxy, kiểm tra việc chuyển tiếp Host, X-Forwarded-Proto và hỗ trợ WebSocket. Sau khi cấp chứng chỉ thành công, bật chuyển hướng HTTPS.

Không cần mở công khai cổng database hoặc Redis để sử dụng ERPNext.

9. Đăng nhập và thiết lập ban đầu

Truy cập https://erp.example.com/desk. Đăng nhập bằng tài khoản Administrator và mật khẩu đã đặt khi tạo site.

ERPNext đã có CRM tích hợp để quản lý Lead, Opportunity và Customer. Frappe CRM giao diện riêng là ứng dụng bổ sung, cần triển khai riêng nếu muốn sử dụng.

10. Các lỗi thường gặp

Xem log ứng dụng:

docker compose -p my_erp   -f /opt/my-erp/compose.yaml   logs --tail=100 backend frontend

Kiểm tra dung lượng:

df -h /
df -i /
docker system df

Các container ERPNext dùng chung lớp image. Vì vậy, không cộng kích thước hiển thị của từng container để kết luận tổng dung lượng sử dụng.

11. Sao lưu trước khi sử dụng thật

Tạo backup database và tệp:

docker compose -p my_erp   -f /opt/my-erp/compose.yaml   exec -T backend bench --site erp.example.com   backup --with-files

Cần lưu backup ra ngoài VPS và bảo vệ cả site_config.json, vì file này có khóa mã hóa cần thiết cho quá trình khôi phục. Một bản backup chỉ có giá trị khi đã kiểm tra khả năng phục hồi.

Trước khi đưa vào vận hành, hãy thử tạo khách hàng, sản phẩm, báo giá; kiểm tra phân quyền nhân viên; theo dõi tài nguyên và thiết lập lịch sao lưu.

Cài đặt thành công là bước khởi đầu. Giá trị của ERPNext đến từ việc thiết kế dữ liệu, phân quyền và quy trình phù hợp với cách doanh nghiệp thực sự làm việc.

Tài liệu tham khảo chính thức

• ERPNext trên GitHub
• Frappe Docker
• Tạo và quản lý website trong FlashPanel