Full Stack FastAPI Template

1. Full Stack FastAPI Template là gì?

Full Stack FastAPI Template là một bộ khung dựng sẵn cho một ứng dụng web hoàn chỉnh, do nhóm làm ra FastAPI duy trì. Thay vì tự lắp từng phần, bạn nhận ngay một trang web có đăng nhập, trang quản trị người dùng, cơ sở dữ liệu, gửi email khôi phục mật khẩu và tài liệu API tự sinh. Việc của bạn là sửa nó thành sản phẩm của mình.

Nói thẳng: đây là công cụ cho lập trình viên, không phải ứng dụng để dùng ngay. Chạy nó lên bạn chỉ thấy một trang quản trị mẫu với mục "Items" để thêm, sửa, xóa dữ liệu thử. Giá trị nằm ở mã nguồn bên dưới.

Bộ khung dùng giấy phép MIT: miễn phí, được sửa và dùng cho dự án thương mại. Chạy trên máy bạn không mất tiền. Chỉ khi đưa lên mạng bạn mới phải trả tiền máy chủ hoặc dịch vụ bạn chọn.

Hợp với bạn nếu:

• Bạn đang học Python hoặc React và muốn xem một dự án thật được tổ chức thế nào.
• Bạn cần khởi đầu nhanh một sản phẩm web có đăng nhập và cơ sở dữ liệu.
• Bạn chịu khó gõ vài lệnh và đọc thông báo lỗi tiếng Anh.

Chưa hợp nếu:

• Bạn muốn làm website mà không viết mã. Hãy tìm công cụ kéo thả.
• Bạn chưa biết gì về lập trình và chỉ muốn "cài xong là dùng".
• Máy bạn yếu hoặc còn ít ổ cứng: Docker phải tải và chạy nhiều dịch vụ cùng lúc.

2. Cần chuẩn bị gì?

Máy tính: Windows, macOS hoặc Linux. Không chạy được trên điện thoại. Tài liệu của dự án không công bố cấu hình tối thiểu.

Tài khoản: tài khoản GitHub (miễn phí) nếu bạn muốn tạo bản sao riêng bằng nút "Use this template". Không cần khóa API nào để chạy trên máy.

Phần mềm phải cài trước:

Phần mềm	Là gì	Cần cho cách nào	Tải ở đâu
Git	Công cụ tải và quản lý mã nguồn	Cả hai cách	https://git-scm.com/downloads
Docker Desktop	Chạy các dịch vụ trong "hộp" riêng (container), khỏi cài từng thứ lên máy	Cả hai cách	https://www.docker.com/
uv	Công cụ cài Python và thư viện Python	Chỉ Cách B	https://docs.astral.sh/uv/
Bun	Công cụ chạy và cài thư viện cho phần giao diện	Chỉ Cách B	https://bun.sh/

Người mới nên đi Cách A: chỉ cần Git và Docker. Cách B dành cho lúc bạn bắt đầu sửa mã và muốn thấy thay đổi tức thì.

3. Cài đặt từng bước

Bước 1: Tạo bản sao của riêng bạn

Mở https://github.com/fastapi/full-stack-fastapi-template, bấm nút Use this template ở phía trên, chọn Create a new repository, đặt tên rồi tạo. Đây là cách dự án hướng dẫn.

Thấy gì là đúng: bạn được đưa tới một repo mới nằm trong tài khoản của bạn, có đủ các thư mục backend, frontend và file compose.yml.

Bước 2: Tải bản sao về máy

Thay <ten-tai-khoan> và <ten-repo> bằng tên tài khoản và tên repo bạn vừa tạo:

git clone https://github.com/<ten-tai-khoan>/<ten-repo>.git
cd <ten-repo>

Thấy gì là đúng: lệnh git clone chạy xong không báo lỗi, và bạn đang đứng trong thư mục dự án.

Bước 3: Mở Docker Desktop

Mở ứng dụng Docker Desktop và chờ tới khi nó báo đang chạy. Kiểm tra bằng lệnh:

docker compose version

Thấy gì là đúng: một dòng có số phiên bản Docker Compose. Nếu báo lỗi, xem mục 5.

Bước 4 (Cách A): Chạy toàn bộ bằng Docker Compose

Đứng ở thư mục gốc của dự án, chạy lần lượt:

docker compose run --rm backend bash scripts/prestart.sh

Lệnh này chuẩn bị cơ sở dữ liệu và tạo tài khoản quản trị đầu tiên. Lần đầu sẽ lâu vì Docker phải tải và dựng các thành phần.

docker compose watch

Lệnh này khởi động mọi dịch vụ và giữ cửa sổ dòng lệnh ở trạng thái đang chạy. Đừng đóng cửa sổ.

Thấy gì là đúng: mở http://localhost:8000 trên trình duyệt và thấy trang đăng nhập. Theo tài liệu, lần đầu có thể mất khoảng một phút để mọi dịch vụ sẵn sàng.

Bước 4 (Cách B): Chạy kiểu phát triển với uv và Bun

Cách này chỉ chạy cơ sở dữ liệu và hộp thư thử bằng Docker; phần còn lại chạy thẳng trên máy.

Ở thư mục gốc:

docker compose up -d db mailpit

Vào thư mục backend rồi cài thư viện, chuẩn bị cơ sở dữ liệu và chạy máy chủ API:

cd backend
uv sync
uv run bash scripts/prestart.sh
uv run fastapi dev

Mở một cửa sổ dòng lệnh thứ hai, đứng ở thư mục gốc của dự án (không phải backend):

bun install
bun run dev

Thấy gì là đúng: http://localhost:5173 hiện trang đăng nhập, và http://localhost:8000/docs hiện trang tài liệu API.

Lưu ý: Trên Windows, các lệnh có bash scripts/prestart.sh cần môi trường có bash. Git for Windows đi kèm Git Bash; hoặc dùng Cách A, khi đó lệnh bash chạy bên trong container.

4. Dùng lần đầu

1. Mở file .env ở thư mục gốc bằng trình soạn thảo văn bản. Tìm hai dòng FIRST_SUPERUSER (email, mặc định admin@example.com) và FIRST_SUPERUSER_PASSWORD (mật khẩu).
2. Mở trang đăng nhập (http://localhost:8000 với Cách A, http://localhost:5173 với Cách B) và đăng nhập bằng hai giá trị đó.
3. Vào mục Items, thêm một mục mới. Mục vừa thêm xuất hiện trong danh sách. Dữ liệu này đã đi qua API và được lưu vào cơ sở dữ liệu PostgreSQL.
4. Mở http://localhost:8000/docs. Đây là tài liệu API tương tác: mỗi đường dẫn của máy chủ có thể bấm thử ngay trên trang.
5. Mở http://localhost:8025. Đây là Mailpit, hộp thư giả dùng khi phát triển. Thử chức năng quên mật khẩu, email sẽ hiện ở đây thay vì gửi đi thật.

Các địa chỉ có sẵn:

Địa chỉ	Là gì	Cách A	Cách B
http://localhost:8000	Ứng dụng (giao diện và API)	Có	Chỉ API
http://localhost:5173	Giao diện khi phát triển	Không	Có
http://localhost:8000/docs	Tài liệu API tương tác	Có	Có
http://localhost:8025	Hộp thư thử Mailpit	Có	Có
http://localhost:8080	Adminer, trang quản trị cơ sở dữ liệu	Có	Không
http://localhost:8090	Bảng điều khiển Traefik (bộ định tuyến)	Có	Không

Khi muốn sửa: mô hình dữ liệu ở backend/app/models.py, các đường dẫn API trong backend/app/api/, giao diện trong thư mục frontend.

5. Lỗi thường gặp và cách sửa

Cổng 8000 đã bị chiếm

• Dấu hiệu: docker compose watch báo lỗi không mở được cổng 8000 (thường có cụm "port is already allocated" hoặc "address already in use").
• Nguyên nhân: bạn còn để uv run fastapi dev chạy, hoặc một chương trình khác đang dùng cổng 8000. Tài liệu dự án nhắc rõ: máy chủ chạy tay và bản trong Compose dùng chung cổng này.
• Cách sửa: dừng máy chủ chạy tay (Ctrl+C trong cửa sổ đó) rồi chạy lại. Tình huống tương tự có thể xảy ra với các cổng 80, 5432, 8025, 8080, 8090 mà bộ khung cũng dùng.

Không kết nối được Docker

• Dấu hiệu: lệnh docker báo "Cannot connect to the Docker daemon", hoặc "docker: command not found".
• Nguyên nhân: Docker Desktop chưa mở, hoặc chưa cài.
• Cách sửa: mở Docker Desktop, chờ nó chạy xong rồi thử lại. Nếu vừa cài, đóng và mở lại cửa sổ dòng lệnh.

Trang chưa lên sau khi chạy

• Dấu hiệu: http://localhost:8000 báo không kết nối được dù lệnh không lỗi.
• Nguyên nhân: các dịch vụ chưa khởi động xong.
• Cách sửa: chờ thêm, và xem nhật ký bằng lệnh dưới đây để biết dịch vụ nào đang kẹt.

docker compose logs backend

Sửa file .env nhưng không thấy thay đổi

• Dấu hiệu: đổi mật khẩu hoặc tên dự án trong .env nhưng ứng dụng vẫn như cũ.
• Nguyên nhân: các container đọc biến môi trường lúc khởi động.
• Cách sửa: dừng (Ctrl+C) rồi chạy lại docker compose watch.

Sửa giao diện nhưng trang ở cổng 8000 không đổi

• Dấu hiệu: với Cách B, trang ở cổng 5173 đã đổi nhưng trang ở cổng 8000 vẫn cũ.
• Nguyên nhân: cổng 8000 phục vụ bản giao diện đã được đóng gói sẵn.
• Cách sửa: vào thư mục frontend và đóng gói lại.

bun run build

Thiếu uv hoặc Bun

• Dấu hiệu: "uv: command not found" hoặc "bun: command not found".
• Nguyên nhân: chưa cài, hoặc cửa sổ dòng lệnh mở trước khi cài.
• Cách sửa: cài theo link ở mục 2, mở lại cửa sổ dòng lệnh. Hoặc dùng Cách A, không cần hai công cụ này.

6. Gỡ cài đặt / cập nhật

Dừng: bấm Ctrl+C ở cửa sổ đang chạy docker compose watch, rồi chạy:

docker compose down

Gỡ sạch: lệnh dưới đây là lệnh chuẩn của Docker Compose, dừng mọi thứ và xóa luôn dữ liệu đã lưu trong cơ sở dữ liệu thử:

docker compose down -v

Sau đó xóa thư mục dự án. Docker Desktop, Git, uv, Bun gỡ theo cách gỡ ứng dụng thông thường nếu bạn không dùng nữa.

Cập nhật: vì bạn tạo bản sao bằng "Use this template", dự án của bạn tách hẳn khỏi bản gốc và không tự nhận bản mới. Tài liệu của bộ khung không mô tả cách kéo thay đổi từ bản gốc. Hãy theo dõi file release-notes.md và trang Releases của repo gốc để biết có gì mới, rồi tự áp dụng phần bạn cần. Bản phát hành mới nhất tại thời điểm viết là 0.12.0 (ngày 12/8/2026).

7. Câu hỏi hay gặp

Có mất tiền không? Không, khi chạy trên máy. Khi đưa lên mạng, bạn trả tiền cho nơi bạn đặt ứng dụng. Dự án có hai tài liệu triển khai: deployment.md (lên FastAPI Cloud) và deployment-docker-compose.md (lên máy chủ riêng bằng Docker Compose). Giá xem ở trang chính thức của dịch vụ bạn chọn.

Có cần mạng không? Cần khi cài đặt, vì Docker, uv và Bun phải tải thành phần về. Sau đó ứng dụng chạy hoàn toàn trên máy bạn tại địa chỉ localhost.

Dữ liệu có bị gửi đi đâu không? Khi chạy trên máy, dữ liệu nằm trong cơ sở dữ liệu PostgreSQL chạy bằng Docker ngay trên máy bạn. Email không được gửi ra ngoài mà bị Mailpit giữ lại để bạn xem.

Mật khẩu trong file .env có an toàn không? File .env có sẵn chỉ chứa giá trị mặc định để chạy thử và nằm công khai trong repo. Tài liệu dặn không lưu bí mật của bản chạy thật vào đó; khi triển khai phải tạo khóa và mật khẩu mới theo hướng dẫn trong hai file triển khai.

Tôi chỉ cần API, không cần giao diện thì sao? Được. File frontend/README.md có mục "Removing the Frontend" liệt kê từng bước gỡ phần giao diện.