thankcard-system/docker/README.md

Laravel Docker Setup - thankcard-system

1. Cấu trúc thư mục

thankcard-system/
├─ .env
├─ artisan
├─ composer.json
├─ public/
├─ storage/
├─ bootstrap/
├─ doc/
└─ docker/
   ├─ docker-compose.yml
   ├─ Dockerfile
   ├─ README.md
   ├─ env/
   │  └─ .env.app
   ├─ nginx/
   │  └─ default.conf
   └─ php/
      └─ entrypoint.sh

---

2. Khởi chạy dự án (Docker)

Đứng tại thư mục root của dự án thankcard-system và chạy:

docker compose -f docker/docker-compose.yml up -d --build

Hoặc di chuyển vào thư mục docker/ rồi chạy:

cd docker
docker compose up -d --build

Sau khi các container chạy thành công, truy cập hệ thống tại trình duyệt:

http://localhost:8888

---

3. Cơ chế cấu hình môi trường (.env)

• File .env chính của Laravel vẫn nằm ở thư mục root để phục vụ máy local.
• Khi chạy trong container Docker, hệ thống sẽ sử dụng file docker/env/.env.app để ghi đè các cấu hình cần thiết (ví dụ: DB_HOST=host.docker.internal giúp PHP container kết nối ra cơ sở dữ liệu trên máy thật).

---

4. Các lệnh cần chạy thủ công khi cập nhật code

4.1. Khi thêm/cập nhật thư viện mới (composer.json)

Khi cập nhật hoặc cài đặt gói package PHP mới, bạn cần chạy lệnh cài đặt bên trong container:

docker compose -f docker/docker-compose.yml exec app composer install

4.2. Khi cập nhật giao diện (CSS / JS / Tailwind classes mới)

Cập nhật giao diện cần biên dịch lại tài nguyên frontend. Bạn có 2 cách:

1️⃣ Chạy trên máy host (đề xuất)

npm install   # một lần, nếu chưa có các package
npm run dev   # Vite dev server, hot‑reload

2️⃣ Chạy trong Docker (sử dụng container node)

# Cài đặt các package (chỉ chạy 1 lần)
docker compose -f docker/docker-compose.yml exec node npm install

# Chế độ phát triển (hot‑reload)
docker compose -f docker/docker-compose.yml exec node npm run dev

# Hoặc biên dịch bản production
docker compose -f docker/docker-compose.yml exec node npm run build

Container node đã expose port 5173, cho phép truy cập Vite dev server tại http://localhost:5173. Khi npm run dev đang chạy, mọi thay đổi CSS/JS sẽ tự động cập nhật trong container app nhờ volume mount.

4.3. Khi cập nhật Database (Migrations)

Để cập nhật cơ sở dữ liệu khi có migrations mới:

docker compose -f docker/docker-compose.yml exec app php artisan migrate

4.4. Khi chạy dữ liệu mẫu (Seeders)

Để tạo dữ liệu mẫu (seed) vào cơ sở dữ liệu:

docker compose -f docker/docker-compose.yml exec app php artisan db:seed

Nếu chỉ muốn chạy một file seeder cố định (ví dụ: UserSeeder):

docker compose -f docker/docker-compose.yml exec app php artisan db:seed --class=UserSeeder

Hoặc để vừa chạy lệnh migrate vừa tự động seed luôn dữ liệu:

docker compose -f docker/docker-compose.yml exec app php artisan migrate --seed

4.5. Khi chỉnh sửa file .env hoặc .env.app

Bạn cần khởi động lại container để cập nhật biến môi trường mới và tiến hành xóa cache cấu hình:

# 1. Restart container app
docker compose -f docker/docker-compose.yml restart app

# 2. Xóa cache cấu hình trong container
docker compose -f docker/docker-compose.yml exec app php artisan config:clear

4.6. Mở công cụ quản lý Database (phpMyAdmin)

Dự án có sẵn một file cấu hình riêng để mở giao diện quản lý MySQL (đã được trỏ sẵn vào database trên máy bạn):

docker compose -f docker/docker-compose.phpmyadmin.yml up -d

Sau đó truy cập: http://localhost:8889 để vào phpMyAdmin.

---

5. Các lệnh tiện ích khác

• Truy cập vào Bash của container app:

  docker compose -f docker/docker-compose.yml exec app bash
  

• Xem log Laravel thời gian thực:

  docker compose -f docker/docker-compose.yml exec app tail -f storage/logs/laravel.log
  

• Dọn dẹp toàn bộ cache của Laravel:

  docker compose -f docker/docker-compose.yml exec app php artisan optimize:clear
  

• Dừng các container:

  docker compose -f docker/docker-compose.yml down
  

docker compose -f docker/docker-compose.yml exec app php artisan key:generate