184 lines
4.9 KiB
Markdown
184 lines
4.9 KiB
Markdown
# tromcho.net
|
|
|
|
Repository này chứa toàn bộ source code của website **tromcho.net**.
|
|
|
|
## Giới thiệu
|
|
|
|
`tromcho.net` là mã nguồn website được tổ chức để phục vụ phát triển, triển khai và vận hành theo quy trình chuẩn trên GitHub.
|
|
README này đóng vai trò tài liệu khởi đầu cho lập trình viên, DevOps engineer và cộng tác viên khi tiếp cận repository.
|
|
|
|
## Mục tiêu repository
|
|
|
|
- Quản lý tập trung toàn bộ source code của website.
|
|
- Chuẩn hóa quy trình phát triển, review và triển khai.
|
|
- Tạo nền tảng rõ ràng cho việc CI/CD, kiểm thử và vận hành production.
|
|
- Hỗ trợ onboarding nhanh cho thành viên mới.
|
|
|
|
## Cấu trúc thư mục đề xuất
|
|
|
|
```text
|
|
.
|
|
├── app/ # Source code ứng dụng chính
|
|
├── public/ # Static files, images, favicon, robots.txt
|
|
├── config/ # Cấu hình môi trường, app, service integration
|
|
├── database/ # Migration, seed, schema
|
|
├── tests/ # Unit test, integration test, e2e test
|
|
├── scripts/ # Script hỗ trợ build, deploy, backup, maintenance
|
|
├── docs/ # Tài liệu kỹ thuật, kiến trúc, quy trình
|
|
├── .github/ # GitHub Actions, issue template, PR template
|
|
├── Dockerfile # Build image ứng dụng
|
|
├── docker-compose.yml # Chạy local/dev bằng container
|
|
├── .env.example # Biến môi trường mẫu
|
|
└── README.md
|
|
```
|
|
|
|
> Cấu trúc thực tế có thể thay đổi theo framework đang sử dụng.
|
|
|
|
## Yêu cầu môi trường
|
|
|
|
Tùy theo stack công nghệ của website, môi trường phát triển nên có:
|
|
|
|
- Git
|
|
- Docker và Docker Compose
|
|
- Node.js / PHP / Python / runtime phù hợp với dự án
|
|
- Make (khuyến nghị)
|
|
- Truy cập vào file cấu hình môi trường `.env`
|
|
|
|
## Bắt đầu nhanh
|
|
|
|
### 1. Clone repository
|
|
|
|
```bash
|
|
git clone https://github.com/<your-org>/tromcho.net.git
|
|
cd tromcho.net
|
|
```
|
|
|
|
### 2. Tạo file môi trường
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Sau đó cập nhật các biến cấu hình cần thiết trong file `.env`.
|
|
|
|
### 3. Chạy môi trường local
|
|
|
|
Nếu dự án dùng Docker:
|
|
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
|
|
Nếu dự án chạy trực tiếp theo framework, sử dụng lệnh tương ứng của stack hiện tại.
|
|
|
|
## Quy trình phát triển
|
|
|
|
- Tạo branch mới từ `main` hoặc `develop`.
|
|
- Đặt tên branch rõ ràng, ví dụ: `feature/homepage-banner`, `fix/login-timeout`.
|
|
- Commit ngắn gọn, đúng ngữ cảnh thay đổi.
|
|
- Tạo Pull Request để review trước khi merge.
|
|
- Không commit file bí mật như `.env`, private key hoặc credential.
|
|
|
|
## Quy ước commit
|
|
|
|
Khuyến nghị dùng convention sau:
|
|
|
|
```text
|
|
feat: thêm chức năng mới
|
|
fix: sửa lỗi
|
|
refactor: tái cấu trúc mã nguồn
|
|
chore: cập nhật tác vụ phụ trợ
|
|
ci: thay đổi pipeline CI/CD
|
|
docs: cập nhật tài liệu
|
|
test: bổ sung hoặc cập nhật kiểm thử
|
|
```
|
|
|
|
## CI/CD
|
|
|
|
Repository nên tích hợp các bước tự động sau:
|
|
|
|
- Lint source code
|
|
- Chạy unit test / integration test
|
|
- Build artifact hoặc Docker image
|
|
- Scan bảo mật dependency/container
|
|
- Deploy tới staging hoặc production theo rule xác định
|
|
|
|
Ví dụ vị trí cấu hình pipeline:
|
|
|
|
```text
|
|
.github/workflows/
|
|
```
|
|
|
|
## Biến môi trường
|
|
|
|
Không commit file `.env` thật lên GitHub.
|
|
Nên cung cấp `.env.example` với:
|
|
|
|
- Danh sách biến bắt buộc
|
|
- Giá trị mẫu an toàn
|
|
- Ghi chú ngắn cho từng biến quan trọng
|
|
|
|
Ví dụ:
|
|
|
|
```env
|
|
APP_ENV=local
|
|
APP_DEBUG=true
|
|
APP_URL=http://localhost
|
|
DB_HOST=127.0.0.1
|
|
DB_PORT=3306
|
|
DB_NAME=tromcho
|
|
DB_USER=user
|
|
DB_PASSWORD=change_me
|
|
```
|
|
|
|
## Triển khai
|
|
|
|
Khuyến nghị tách rõ các môi trường:
|
|
|
|
- local
|
|
- development
|
|
- staging
|
|
- production
|
|
|
|
Các thành phần nên được chuẩn hóa khi triển khai:
|
|
|
|
- Biến môi trường
|
|
- Reverse proxy / web server
|
|
- TLS certificate
|
|
- Database migration
|
|
- Backup strategy
|
|
- Log rotation và monitoring
|
|
|
|
## Bảo mật
|
|
|
|
- Không đưa secrets vào source code.
|
|
- Bật branch protection cho nhánh quan trọng.
|
|
- Review dependency định kỳ.
|
|
- Áp dụng nguyên tắc least privilege cho tài khoản deploy.
|
|
- Theo dõi log, audit và cảnh báo bất thường.
|
|
|
|
## Đóng góp
|
|
|
|
Khi đóng góp vào repository:
|
|
|
|
1. Fork hoặc tạo branch làm việc.
|
|
2. Cập nhật mã nguồn theo phạm vi thay đổi.
|
|
3. Kiểm tra local trước khi tạo Pull Request.
|
|
4. Viết mô tả PR rõ ràng: mục tiêu, phạm vi ảnh hưởng, cách kiểm thử.
|
|
|
|
## Tài liệu nên bổ sung
|
|
|
|
Repository này nên có thêm các tài liệu sau trong thư mục `docs/`:
|
|
|
|
- Kiến trúc hệ thống
|
|
- Sơ đồ database
|
|
- Luồng deploy
|
|
- Quy trình backup/restore
|
|
- Hướng dẫn xử lý sự cố
|
|
- Checklist release
|
|
|
|
## License
|
|
|
|
Copyright 2026 Trộm Chó chấm Nét
|
|
---
|