Hướng Dẫn Self-Host Karakeep Trên VPS Với AI Tagging Bằng Docker A-Z

Self-Host Karakeep trên VPS là giải pháp tối ưu giúp bạn sở hữu một kho lưu trữ bookmark và ghi chú cá nhân hóa mạnh mẽ mà không lo rò rỉ dữ liệu quan trọng. Khi lưu lại hàng trăm liên kết mỗi tuần, việc tìm kiếm lại thông tin thường biến thành “cơn ác mộng” nếu thiếu sự sắp xếp khoa học. Thay vì gửi toàn bộ nội dung web nhạy cảm đến các nền tảng trí tuệ nhân tạo đám mây của bên thứ ba, bạn hoàn toàn có thể triển khai hệ thống gắn tag tự động bằng mô hình AI cục bộ với Ollama trên nền tảng máy chủ ảo tối ưu từ ThueVPSGiaRe.vn.

1. Chuẩn bị môi trường VPS và tài nguyên hệ thống

Trước khi đi vào các thao tác kỹ thuật, bạn cần chuẩn bị một máy chủ đáp ứng đủ yêu cầu tính toán của mô hình AI nội bộ. Hệ thống hướng dẫn trong bài viết này vận hành ổn định trên nền tảng Ubuntu 24.04 LTS với quyền quản trị root/sudo.

• Tài nguyên phần cứng khuyến nghị: Cần chuẩn bị máy chủ ảo sở hữu tối thiểu 4 CPU cores và 8 GB RAM. Mô hình AI phục vụ tagging sẽ tiêu tốn khoảng 3.2 GB bộ nhớ RAM trong trạng thái được nạp (loaded). Bạn có thể tham khảo thêm khả năng chạy container của VPS 8GB RAM để nắm rõ cách tối ưu phân bổ tài nguyên.
• Tên miền và bản ghi DNS: Chuẩn bị một tên miền hoặc subdomain (ví dụ: karakeep.example.com) đã tạo bản ghi A trỏ chính xác về địa chỉ IPv4 của VPS. Hãy đảm bảo bạn biết cách trỏ domain chuẩn xác về địa chỉ IP máy chủ của mình.
• Cổng mạng (Ports): Đảm bảo cổng 80 và 443 mở ra ngoài internet để web server Caddy có thể tự động cấp phát và gia hạn chứng chỉ SSL Let’s Encrypt.
• Môi trường máy chủ: Sử dụng máy chủ mới hoặc máy chủ chưa có tiến trình nào chiếm dụng port 80 và 443. Việc xử lý suy luận AI trên CPU sẽ có tốc độ chậm hơn so với GPU chuyên dụng, tuy nhiên tác vụ tagging này chạy hoàn toàn ở chế độ nền (background) nên bạn không nhất thiết phải đầu tư máy chủ GPU tốn kém.

2. Cài đặt Docker, Docker Compose V2 và Caddy Server

Hệ thống của chúng ta sử dụng Docker để cô lập 4 dịch vụ chính và Caddy làm reverse proxy tiếp nhận lưu lượng truy cập từ bên ngoài. Tất cả các gói phần mềm cần thiết đều có thể cài đặt trực tiếp từ kho lưu trữ chính thức của Ubuntu.

Trước tiên, bạn cập nhật danh sách gói và tiến hành cài đặt Docker Engine, Docker Compose V2, máy chủ web Caddy, OpenSSL cùng cURL:

sudo apt-get update
sudo apt-get install -y docker.io docker-compose-v2 caddy openssl curl
sudo systemctl enable --now docker

Nếu bạn muốn hiểu rõ hơn cơ chế quản lý container hiện đại này, bài viết cài đặt và sử dụng Docker Compose trên Ubuntu chuẩn V2 sẽ cung cấp góc nhìn toàn diện cho bạn.

Tiếp theo, hãy thiết lập tường lửa UFW để bảo vệ máy chủ. Bạn mở cổng dịch vụ SSH, HTTP (cổng 80) và HTTPS (cổng 443). Hãy lưu ý thay thế cổng SSH thực tế nếu máy chủ của bạn không dùng cổng 22 mặc định:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Để chủ động kiểm soát lưu lượng mạng vào máy chủ, bạn nên xem thêm bài viết thiết lập tường lửa UFW trên Ubuntu. Lưu ý quan trọng: Bản thân ứng dụng Karakeep chỉ lắng nghe trên cổng nội bộ 127.0.0.1:3000, do đó bạn không cần và không được mở cổng 3000 trên tường lửa UFW ra bên ngoài.

3. Thiết lập biến môi trường và file Compose cho Karakeep

Chúng ta sẽ gom toàn bộ cấu hình vào một thư mục làm việc riêng biệt, đồng thời phân quyền chặt chẽ cho file chứa các khóa bí mật để tăng cường an toàn hệ thống.

Khởi tạo thư mục dự án và tạo file .env với quyền hạn giới hạn chỉ người dùng sở hữu mới có quyền đọc ghi:

mkdir -p ~/karakeep
cd ~/karakeep
touch .env
chmod 600 .env
openssl rand -hex 32
openssl rand -hex 32

Lệnh openssl rand -hex 32 sẽ in ra 2 chuỗi ngẫu nhiên có độ dài 32 ký tự. Bạn mở file ~/karakeep/.env và điền nội dung cấu hình như sau (thay thế chuỗi ngẫu nhiên thứ nhất vào NEXTAUTH_SECRET, chuỗi thứ hai vào MEILI_MASTER_KEY):

KARAKEEP_VERSION=0.33.2
NEXTAUTH_URL=https://karakeep.example.com
NEXTAUTH_SECRET=REPLACE_WITH_FIRST_VALUE
MEILI_MASTER_KEY=REPLACE_WITH_SECOND_VALUE
OPENAI_API_KEY=ollama
INFERENCE_TEXT_MODEL=qwen3:4b-instruct
INFERENCE_JOB_TIMEOUT_SEC=300

Giải thích các biến đặc thù: Giá trị OPENAI_API_KEY=ollama chỉ là một chuỗi giữ chỗ (placeholder), không phải API key trả phí. Karakeep bắt buộc cần một giá trị tại biến này để gọi giao diện API tương thích chuẩn OpenAI của Ollama. Tham số INFERENCE_JOB_TIMEOUT_SEC=300 kéo dài thời gian chờ lên 5 phút để mô hình chạy trên CPU có đủ thời gian hoàn thành tác vụ (mức mặc định 30 giây là quá ngắn khi xử lý không có GPU).

Tiếp tục tạo file cấu hình triển khai dịch vụ ~/karakeep/compose.yaml với nội dung:

services:
  web:
    image: ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION}
    restart: unless-stopped
    env_file:
      - .env
    environment:
      DATA_DIR: /data
      MEILI_ADDR: http://meilisearch:7700
      BROWSER_WEB_URL: http://chrome:9222
      OPENAI_BASE_URL: http://ollama:11434/v1
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - data:/data
    depends_on:
      - meilisearch
      - chrome
      - ollama

  chrome:
    image: ghcr.io/karakeep-app/karakeep-chrome:151.0.7922.47-r1
    restart: unless-stopped
    init: true
    command:
      - --disable-gpu
      - --disable-dev-shm-usage
      - --hide-scrollbars
      - --disable-blink-features=AutomationControlled
      - --window-size=1440,900

  meilisearch:
    image: getmeili/meilisearch:v1.41.0
    restart: unless-stopped
    environment:
      MEILI_MASTER_KEY: ${MEILI_MASTER_KEY}
      MEILI_NO_ANALYTICS: "true"
    volumes:
      - meilisearch:/meili_data

  ollama:
    image: ollama/ollama:0.35.1
    restart: unless-stopped
    volumes:
      - ollama:/root/.ollama

volumes:
  data:
  meilisearch:
  ollama:

Cấu trúc file Compose trên dựa trên bản chuẩn upstream của tác giả với các image tag được ghim phiên bản cụ thể (pinned versions) và bổ sung dịch vụ Ollama. Container ollama không hề có mục ports, nghĩa là cổng của nó không bị public ra máy chủ host. Các container trong cùng mạng Compose nội bộ vẫn có thể kết nối với nhau bình thường. Tuyệt đối không đưa cổng 11434 ra môi trường internet vì mặc định Ollama không có cơ chế xác thực người dùng.

Kiểm tra cú pháp và tiến hành kích hoạt toàn bộ hệ thống:

sudo docker compose config --quiet
sudo docker compose up -d
sudo docker compose ps
curl -s http://127.0.0.1:3000/api/health

Kết quả trả về yêu cầu cả 4 container đều ở trạng thái Up, và lệnh kiểm tra health check trả về chuỗi JSON: {"status":"ok","message":"Web app is working"}.

4. Tìm hiểu vai trò 4 dịch vụ cốt lõi trong stack

Để dễ dàng làm chủ và bảo trì hệ thống lâu dài, bạn cần hiểu rõ cách thức phân chia trách nhiệm giữa các container và luồng dữ liệu bên trong.

• Web service (Karakeep): Đóng vai trò ứng dụng trung tâm, hiển thị giao diện người dùng và điều phối toàn bộ các tác vụ nền (background jobs).
• Chrome service (Headless Chrome): Thực hiện việc truy cập, tải toàn bộ nội dung của trang liên kết và chụp ảnh hoặc kết xuất nội dung văn bản.
• Meilisearch: Cơ sở dữ liệu tìm kiếm tốc độ cao, lập chỉ mục toàn bộ văn bản được cào về để bạn có thể tìm kiếm toàn văn sau này.
• Ollama: Nền tảng chạy mô hình AI cục bộ, tiếp nhận nội dung văn bản tóm tắt từ web service để suy luận và đề xuất các nhãn dán (tags) tương ứng.

Caddy hoạt động như một điểm truy cập HTTPS công khai an toàn; nó chuyển tiếp yêu cầu đến ứng dụng web trên địa chỉ loopback của máy chủ. Trình duyệt người dùng không bao giờ cần kết nối trực tiếp đến Meilisearch hay Ollama.

Các volume được đặt tên (named volumes) giúp lưu trữ dữ liệu ứng dụng, chỉ mục tìm kiếm và các mô hình AI đã tải về nằm ngoài tầng ghi của container. Nhờ đó, việc khởi tạo lại container sẽ không làm mất dữ liệu.

Lưu ý về tính riêng tư: Việc chạy suy luận AI cục bộ không biến thao tác thu thập trang thành hoạt động offline. Trình cào dữ liệu (crawler) vẫn phải kết nối internet tới các trang web bạn lưu, quá trình cài đặt stack và mô hình vẫn cần tải xuống từ mạng. Lợi ích bảo mật ở đây là nội dung trang web được phân tích bởi chính mô hình AI do bạn làm chủ, không gửi dữ liệu tới OpenAI hay bất kỳ nhà cung cấp AI đám mây nào khác.

5. Tải mô hình AI Qwen3 phục vụ gán nhãn tự động

Sau khi container Ollama đã vận hành, bạn cần tải mô hình AI được chỉ định trong cấu hình về hệ thống để thực hiện nhiệm vụ đọc văn bản và đề xuất nhãn dán.

Thực thi lệnh tải mô hình trực tiếp bên trong container Ollama:

sudo docker compose exec ollama ollama pull qwen3:4b-instruct
sudo docker compose exec ollama ollama list

Dung lượng tải về của mô hình khoảng 2.5 GB. Mô hình qwen3:4b-instruct được phát hành dưới giấy phép mã nguồn mở Apache 2.0, có khả năng tuân thủ cấu trúc định dạng tag của Karakeep rất chuẩn xác và có thể vận hành mượt mà trên môi trường CPU thuần túy.

Bạn chỉ nên sử dụng duy nhất một mô hình tagging tại một thời điểm: Ollama sẽ giữ mô hình được sử dụng gần nhất trong RAM trong vài phút, và việc nạp cùng lúc hai mô hình có thể làm cạn kiệt bộ nhớ RAM của một VPS cấu hình nhỏ dẫn đến lỗi treo máy.

6. Cấu hình Reverse Proxy HTTPS tự động qua Caddy

Caddy là web server hiện đại có khả năng tự động xin và kích hoạt chứng chỉ SSL thông qua Let’s Encrypt mà không cần cấu hình dòng lệnh cronjob phức tạp.

Đầu tiên, hãy tạo một bản sao lưu cho file cấu hình Caddy mặc định:

sudo cp -a /etc/caddy/Caddyfile /etc/caddy/Caddyfile.bak

Thay nội dung file /etc/caddy/Caddyfile bằng khối lệnh chuyển tiếp đơn giản sau (thay thế karakeep.example.com bằng tên miền thật của bạn):

karakeep.example.com {
    reverse_proxy 127.0.0.1:3000
}

Tiến hành kiểm tra tính hợp lệ của cấu hình và reload lại Caddy:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -sI https://karakeep.example.com/api/health

Khi lệnh kiểm tra cuối cùng trả về mã HTTP/2 200 mà không xuất hiện bất kỳ cảnh báo lỗi SSL nào, website của bạn đã sẵn sàng truy cập an toàn qua kết nối HTTPS.

7. Khởi tạo tài khoản quản trị và khóa cổng đăng ký

Bất kỳ ai biết được tên miền của bạn đều có thể đăng ký tài khoản cho đến khi tính năng này bị vô hiệu hóa. Do đó, việc thiết lập bảo mật phân quyền là bước bắt buộc ngay sau khi đưa hệ thống lên mạng internet.

1. Mở trình duyệt web, truy cập đường dẫn https://karakeep.example.com và bấm chọn Sign up. Tài khoản đầu tiên đăng ký trên hệ thống sẽ tự động được gán quyền quản trị viên cao nhất (administrator). Bạn có thể tìm hiểu thêm về đặc quyền này qua hướng dẫn về quyền root trong môi trường máy chủ Linux.
2. Ngay sau khi đăng ký thành công, hãy khóa tính năng đăng ký tự do bằng cách thêm dòng sau vào cuối file ~/karakeep/.env:

   DISABLE_SIGNUPS=true

3. Áp dụng thay đổi cấu hình bằng cách chạy lại lệnh:

   sudo docker compose up -d

Sau khi cập nhật, hãy đăng xuất tài khoản và truy cập lại trang đăng ký để kiểm tra. Hệ thống lúc này sẽ hiển thị thông báo Sign Up Unavailable. Nếu muốn tạo thêm tài khoản cho đồng nghiệp hay người thân, bạn có thể đăng nhập tài khoản quản trị, truy cập menu cá nhân, chọn Admin Settings → Users List và tạo tài khoản thủ công qua nút Create User.

8. Kiểm tra tính năng lưu trữ, tìm kiếm và gán nhãn AI

Bây giờ là lúc bạn thử nghiệm khả năng tự động hóa vượt trội của Karakeep kết hợp cùng mô hình ngôn ngữ lớn Qwen3 chạy trên Ollama.

• Lưu liên kết đầu tiên: Chọn mục New Item, dán đường dẫn của một bài báo trực tuyến bất kỳ và lưu lại. Karakeep trước hết sẽ dùng Chrome không đầu để cào dữ liệu trang, sau đó đưa bài viết vào hàng đợi suy luận để AI xử lý nhãn.
• Thời gian phản hồi của mô hình: Các nhãn dán gợi ý thường xuất hiện trên thẻ bookmark trong vòng 1 đến 2 phút. Hệ thống xử lý từng liên kết một theo thứ tự. Lần xử lý đầu tiên sau một khoảng thời gian dài không hoạt động sẽ mất thời gian hơn đôi chút vì Ollama cần nạp lại mô hình vào RAM.
• Ví dụ thực tế: Một bài viết Wikipedia về espresso sau khi lưu đã được AI tự động gắn các tag: Espresso, Espresso Machine, Coffee Machine, Cappuccino, và Third-Wave Coffee. Những mô hình ngôn ngữ nhỏ nhận diện chủ đề chính rất tốt nhưng đôi khi có thể gán thêm những nhãn có tính liên quan rộng, vì vậy bạn nên xem lại và xóa bớt các tag không cần thiết.
• Ghi chú và hình ảnh: Ghi chú dạng văn bản (text notes) cũng được AI gán tag tương tự. Riêng bookmark dạng hình ảnh sẽ đòi hỏi mô hình thị giác chuyên biệt (vision-capable model) – cấu hình hiện tại trong bài viết này chưa thiết lập cho tác vụ ảnh.
• Tùy biến chỉ dẫn AI: Thử tìm kiếm một từ khóa bất kỳ nằm trong thân bài viết để kiểm tra Meilisearch đã lập chỉ mục chính xác chưa. Để định hướng phong cách gán nhãn cho AI theo ý muốn (ví dụ: ngôn ngữ ưu tiên hoặc phong cách đặt tên), hãy vào menu cá nhân, chọn User Settings → AI Settings và bổ sung chỉ dẫn cụ thể.
• Tiện ích mở rộng & App: Khi cài đặt tiện ích trình duyệt hoặc ứng dụng di động của Karakeep, bạn chỉ cần nhập địa chỉ máy chủ https://karakeep.example.com và đăng nhập bằng tài khoản cá nhân vừa tạo.

9. Các bước nghiệm thu hệ thống trước khi import hàng loạt

Trước khi chuyển toàn bộ hàng ngàn liên kết từ trình duyệt cũ sang Karakeep, bạn nên thực hiện quy trình kiểm tra từng giai đoạn để đảm bảo mọi thành phần trong cụm dịch vụ phối hợp nhịp nhàng.

• Kiểm tra 3 bước độc lập: Bắt đầu bằng việc thêm 1 trang bài viết công khai tiêu chuẩn. Đảm bảo tiêu đề và nội dung hiển thị đầy đủ, tìm kiếm từ khóa trong thân bài có kết quả, và AI hoàn thành việc gán nhãn. Ba bước này xác nhận 3 điều khác nhau: lưu URL xác nhận bộ nhớ hoạt động, tìm kiếm được xác nhận crawler và Meilisearch hoạt động, còn có tag xác nhận mô hình AI hoàn tất tác vụ. Phản hồi health check thông thường không thể chứng minh cả 3 công đoạn đều chạy chuẩn.
• Xem xét chất lượng tag: Đánh giá một vài đề xuất nhãn đầu tiên trước khi đổ dữ liệu lớn vào thư viện. Mô hình có thể tạo ra các nhãn hợp lệ nhưng quá rộng hoặc chỉ liên quan gián tiếp. Hãy coi tag như những gợi ý có thể chỉnh sửa chứ không phải bản tóm tắt hoàn hảo của nội dung gốc. Việc giữ các nhãn dán nhất quán sẽ hữu ích hơn việc chấp nhận hàng loạt nhãn trùng lặp gần nghĩa.
• Tránh nhầm lẫn hàng đợi với lỗi: Sau một thời gian không sử dụng, hãy kiên nhẫn chờ vài chục giây để Ollama nạp lại mô hình trước khi cho rằng tác vụ gán nhãn bị lỗi. Việc import cùng lúc một lượng lớn bookmark sẽ tạo ra hàng đợi xử lý nền thay vì phân bổ tiến trình riêng cho từng liên kết. Bạn cũng nên tránh việc liên tục thay đổi mô hình AI trong lúc đang chuẩn đoán lỗi, vì điều đó làm cho vấn đề đầy bộ nhớ RAM và lỗi tên mô hình trở nên phức tạp, khó phân biệt với lỗi thu thập dữ liệu web.

10. Hướng dẫn xử lý các lỗi thường gặp khi tự host Karakeep

Nếu gặp sự cố trong quá trình sử dụng, bước đầu tiên luôn là kiểm tra nhật ký hoạt động (logs) của container ứng dụng web:

cd ~/karakeep
sudo docker compose logs --tail=50 web

Các tình huống lỗi phổ biến và hướng xử lý chi tiết:

• Không xuất hiện bất kỳ nhãn dán nào: Hãy tìm các dòng log chứa từ khóa [inference]. Nếu gặp lỗi 404 model '...' not found, nguyên nhân là giá trị khai báo tại INFERENCE_TEXT_MODEL trong file .env không khớp chính xác với tên hiển thị trong lệnh ollama list. Nếu xuất hiện inference job failed: Error: Timeout, điều này có nghĩa là mô hình AI cần nhiều thời gian hơn mức quy định của INFERENCE_JOB_TIMEOUT_SEC; hãy tăng thông số này lên và áp dụng lại bằng lệnh sudo docker compose up -d.
• Bookmark chỉ hiển thị mỗi URL, không có tiêu đề hay tag: Quá trình cào dữ liệu thất bại nên AI không có dữ liệu đầu vào để phân tích. Tìm kiếm dòng chữ Crawling job failed trong log và kiểm tra xem máy chủ có kết nối mạng được tới trang web đó hay không. Sau đó, bạn có thể mở menu của bookmark đó và chọn More → Refresh để hệ thống tiến hành cào và gán nhãn lại.
• Thông báo “Failed to find potentially relevant tags … Document not found”: Dòng thông báo này có thể hiển thị đối với các bookmark mới tạo trước khi Meilisearch kịp cập nhật chỉ mục tìm kiếm. Lỗi này hoàn toàn bình thường và không làm gián đoạn tiến trình gán tag của hệ thống.
• Ollama tự động dừng hoặc máy chủ bị đơ (freeze): Kích thước mô hình vượt quá dung lượng bộ nhớ khả dụng. Hãy kiểm tra tình trạng tài nguyên bằng lệnh free -h và kiểm tra thông điệp tràn bộ nhớ bằng sudo dmesg | grep -i oom. Bạn cần cấp thêm RAM cho máy chủ, chỉ duy trì 1 mô hình hoạt động duy nhất hoặc đổi sang mô hình ngôn ngữ có kích thước nhẹ hơn. Trong quá trình vận hành, bạn có thể tham khảo thêm các lệnh kiểm tra cấu hình VPS cũng như cách tạo file Swap trên VPS Linux để hỗ trợ bù đắp bộ nhớ tức thời khi RAM đạt đỉnh.
• Chỉnh sửa file .env nhưng không có hiệu lực: Bạn bắt buộc phải chạy lệnh sudo docker compose up -d để Docker cập nhật lại cấu hình. Thao tác restart container thông thường sẽ không nạp lại nội dung mới từ file biến môi trường.
• Lỗi chứng chỉ SSL / Caddy không cấp phát được HTTPS: Hãy kiểm tra xem bản ghi A của tên miền đã thực sự trỏ về đúng IP máy chủ chưa, đồng thời đảm bảo cổng 80 và 443 đang mở và không bị xung đột. Bạn có thể kiểm tra nhật ký chi tiết của Caddy qua lệnh sudo journalctl -u caddy -n 50 --no-pager. Bạn cũng có thể xem thêm hướng dẫn về cài đặt chứng chỉ SSL Let’s Encrypt để nắm rõ nguyên lý xác thực tên miền qua cổng mạng.

Ngoài ra, sau một thời gian dài sử dụng các image và container kiểm thử, dung lượng ổ đĩa của bạn có thể tăng lên. Hãy áp dụng cách dọn dẹp Docker giải phóng dung lượng định kỳ để hệ thống luôn vận hành trơn tru và tránh hiện tượng đầy ổ đĩa làm gián đoạn database.

Lưu ý: Toàn bộ thông tin và hướng dẫn kỹ thuật trong bài viết chỉ mang tính chất tham khảo. Các câu lệnh, thông số môi trường và cú pháp cấu hình có thể thay đổi tùy thuộc vào phiên bản phát hành của Karakeep, Ollama, Docker cũng như hệ điều hành cụ thể. Quản trị viên nên chủ động kiểm tra kỹ lưỡng, sao lưu dữ liệu dự phòng và đánh giá tài nguyên máy chủ trước khi đưa vào vận hành thực tế.