Trong bài viết này, chúng tôi sẽ hướng dẫn chi tiết cách triển khai hai công cụ — maxkb và ollama — sử dụng Docker trên môi trường Windows. Bài viết này phù hợp cho những ai muốn nhanh chóng triển khai, kiểm thử và triển khai các dịch vụ này trên máy cục bộ. Do sự khác biệt giữa môi trường Windows và Linux, bài viết cũng bao gồm hướng dẫn cấu hình Docker Desktop và WSL2.
Môi trường chuẩn bị
Cài đặt Docker Desktop
- Tải Docker Desktop: Truy cập trang web chính thức của Docker để tải gói cài đặt Docker Desktop cho Windows.
- Các bước cài đặt:
- Nhấp đúp vào tệp cài đặt đã tải, làm theo hướng dẫn để hoàn tất quá trình cài đặt.
- Sau khi cài đặt xong, khởi động Docker Desktop và đảm bảo Docker hoạt động bình thường.
- Xác minh qua dòng lệnh: Mở PowerShell hoặc CMD, thực thi lệnh sau để kiểm tra phiên bản Docker:
docker version
Nếu có thể hiển thị thông tin về client và server, điều đó có nghĩa là Docker đã được cài đặt thành công.
Hướng dẫn cấu hình WSL2
Khi sử dụng Docker Desktop trên Windows, nên bật backend WSL2 để có tính tương thích và hiệu suất tốt hơn cho các container Linux:
- Bật WSL2: Đảm bảo Windows đã bật tính năng WSL2, có thể tham khảo tài liệu chính thức của Microsoft.
- Chọn backend WSL2 mặc định: Sau khi khởi động Docker Desktop, trong phần cài đặt, chuyển đến tab "General" và đảm bảo đã chọn "Use the WSL 2 based engine".
Sau khi cấu hình xong, Docker sẽ sử dụng WSL2 làm môi trường chạy container, mang lại trải nghiệm gần gũi hơn với Linux.
Chi tiết triển khai maxkb
Trước khi triển khai, hãy đảm bảo bạn đã hiểu các chức năng cơ bản và yêu cầu chạy của maxkb. Các bước sau sẽ hướng dẫn cách lấy image từ Docker Hub, khởi động container và thực hiện cấu hình đơn giản.
Lấy image maxkb
Thực thi lệnh sau trong dòng lệnh để lấy image maxkb:
docker pull your_dockerhub_account/maxkb:latest
Lưu ý: Vui lòng thay thế
your_dockerhub_account/maxkb:latestbằng địa chỉ image thực tế của dự án.
Khởi động container maxkb
Khi khởi động container, bạn có thể sử dụng lệnh docker run để cấu hình ánh xạ cổng, gắn mount volume, v.v. Ví dụ:
docker run -d --name maxkb \
-p 8080:80 \
-v C:\docker\maxkb\data:/app/data \
your_dockerhub_account/maxkb:latest
Giải thích tham số:
-d: Chạy container ở chế độ nền.--name maxkb: Đặt tên cho container để dễ quản lý.-p 8080:80: Ánh xạ cổng bên trong container (ví dụ 80) đến cổng 8080 trên máy chủ.-v C:\docker\maxkb\data:/app/data: Gắn mount thư mục cục bộ Windows vào thư mục dữ liệu trong container. Điều chỉnh đường dẫn theo yêu cầu của dự án.
Các cấu hình và tham số thông dụng cho container
Tùy theo yêu cầu thực tế của dự án, container maxkb có thể cần các biến môi trường hoặc tệp cấu hình bổ sung:
- Cấu hình biến môi trường:
docker run -d --name maxkb \
-p 8080:80 \
-v C:\docker\maxkb\data:/app/data \
-e MAXKB_CONFIG=/app/config/config.yml \
your_dockerhub_account/maxkb:latest
- Gắn mount tệp cấu hình tùy chỉnh: Theo tài liệu của maxkb, nếu cần gắn mount tệp cấu hình tùy chỉnh, bạn có thể ánh xạ đường dẫn tệp cấu hình cục bộ đến đường dẫn chỉ định trong container.
Chi tiết triển khai ollama
ollama chủ yếu được sử dụng để hiển thị các mô hình AI và giao diện hội thoại, các bước triển khai tương tự như maxkb, tham khảo các bước cụ thể sau.
Lấy image ollama
Lấy image ollama:
docker pull your_dockerhub_account/ollama:latest
Đảm bảo bạn đang sử dụng địa chỉ image chính xác.
Khởi động container ollama
Ví dụ về lệnh khởi động container:
docker run -d --name ollama \
-p 9090:80 \
-v C:\docker\ollama\config:/app/config \
your_dockerhub_account/ollama:latest
Giải thích tham số:
-p 9090:80: Ánh xạ cổng dịch vụ bên trong container (ví dụ 80) đến cổng 9090 trên máy chủ Windows.-v C:\docker\ollama\config:/app/config: Gắn mount thư mục cấu hình cục bộ vào thư mục chỉ định trong container để điều chỉnh tham số.
Cấu hình biến môi trường và ánh xạ cổng
Nếu cần cấu hình biến môi trường cho ollama (ví dụ: chỉ định API Key hoặc cấu hình mô hình), bạn có thể thực hiện như sau:
docker run -d --name ollama \
-p 9090:80 \
-v C:\docker\ollama\config:/app/config \
-e OLLAMA_API_KEY=your_api_key_here \
your_dockerhub_account/ollama:latest
Điều chỉnh các biến môi trường và tham số theo yêu cầu thực tế.
Truy cập và xác minh
Sau khi triển khai, bạn có thể truy cập và kiểm thử thông qua trình duyệt hoặc công cụ API:
- Địa chỉ truy cập maxkb:
Mở trình duyệt, nhập địa chỉ
http://localhost:8080. Nếu triển khai thành công, bạn sẽ thấy trang chủ của maxkb hoặc phản hồi từ giao diện. - Địa chỉ truy cập ollama:
Mở trình duyệt, nhập địa chỉ
http://localhost:9090để kiểm thử.
Ngoài ra, bạn có thể sử dụng lệnh Docker logs để quan sát trạng thái khởi động container và thông tin gỡ lỗi:
docker logs maxkb
docker logs ollama
Các vấn đề thường gặp và giải pháp
- Xung đột cổng
- Vấn đề: Khi khởi động container, thông báo cho biết cổng đã bị chiếm dụng.
- Giải pháp: Kiểm tra tình trạng sử dụng cổng trên máy, sửa đổi cổng ánh xạ trên máy chủ trong lệnh
docker run, ví dụ: thay đổi8080thành các cổng trống khác.
- Gắn mount dữ liệu bất thường
- Vấn đề: Thư mục gắn mount không có dữ liệu hoặc không thể ghi dữ liệu.
- Giải pháp: Kiểm tra quyền truy cập thư mục Windows, đảm bảo Docker Desktop đã được cấp quyền truy cập; đồng thời xác nhận đường dẫn đã được viết đúng.
- Lỗi khởi động container
- Vấn đề: Container khởi động xong lập tức thoát hoặc báo lỗi.
- Giải pháp: Xem nhật ký container (
docker logs tên_container), tìm kiếm các gợi ý lỗi. Thường liên quan đến biến môi trường, tệp cấu hình bị thiếu, điều chỉnh cấu hình theo nhật ký cụ thể.
- Các vấn đề liên quan đến WSL2
- Vấn đề: Trong một số môi trường phát triển, mạng hoặc gắn mount tệp của container gặp sự cố.
- Giải pháp: Xác nhận việc tích hợp WSL2 của Docker Desktop có hoạt động bình thường, nếu cần, cập nhật kernel WSL2 và Docker Desktop lên phiên bản mới nhất.