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

.
├── 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

git clone https://github.com/<your-org>/tromcho.net.git
cd tromcho.net

2. Tạo file môi trường

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:

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:

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:

.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ụ:

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:

Fork hoặc tạo branch làm việc.
Cập nhật mã nguồn theo phạm vi thay đổi.
Kiểm tra local trước khi tạo Pull Request.
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

README.md

tromcho.net

Giới thiệu