Getting Started — football-booking-go-services

Hướng dẫn cài đặt môi trường, cấu hình, và chạy Go services ở local cũng như production.

---

Yêu cầu hệ thống

Tool	Version	Kiểm tra
Go	≥ 1.23	go version
Docker + Docker Compose	≥ 24	docker version
Make	any	make --version
golangci-lint (optional, cho lint)	≥ 1.60	golangci-lint --version

Quan trọng: Shared infra stack (football-booking-infras/docker-compose/stateful-stack.local.yml) phải đang chạy trước vì nó là owner của football-booking-network. Go services chỉ join network đó — xem football-booking-infras/docker-compose/README.md.

---

1. Clone và cài đặt dependencies

git clone https://github.com/sangtrandev00/football-booking-go-services.git
cd football-booking-go-services

# Tải tất cả Go dependencies và tạo go.sum
go mod tidy

---

2. Cấu hình environment

# Copy file mẫu
cp deployments/.env.example deployments/.env

# Mở và điền các giá trị thực
nano deployments/.env

Các biến bắt buộc phải điền:

# Redis password (lấy từ NestJS .env)
REDIS_PASSWORD=...

# PostgreSQL (lấy từ NestJS .env)
DB_ADMIN_PASSWORD=...

# MinIO credentials (nếu dùng document-worker)
MINIO_ACCESS_KEY=...
MINIO_SECRET_KEY=...

# ClickHouse password (nếu dùng analytics-pipeline)
CLICKHOUSE_PASSWORD=...

# Payment webhooks
VNPAY_HASH_SECRET=...
STRIPE_WEBHOOK_SECRET=...

---

3. Chạy local (development)

Option A — Docker Compose (khuyến nghị)

# Đảm bảo NestJS stack đang chạy và network đã tồn tại
docker network ls | grep football-booking-network

# Build images từ source và start tất cả 4 services
make dev

# Hoặc chỉ start một service cụ thể
docker compose -f deployments/docker-compose.yml up -d document-worker

# Xem logs realtime
docker compose -f deployments/docker-compose.yml logs -f document-worker

# Stop
make dev-down

Option B — Chạy trực tiếp (không cần Docker)

Cách này yêu cầu các service infrastructure (Kafka, Redis, Postgres...) đang chạy và accessible từ local machine.

# Compile tất cả services
make build

# Chạy từng service (mỗi terminal riêng)
KAFKA_BROKERS=localhost:9092 \
MINIO_ENDPOINT=localhost:9000 \
MINIO_ACCESS_KEY=minioadmin \
MINIO_SECRET_KEY=minioadmin \
./bin/document-worker

KAFKA_BROKERS=localhost:9092 \
REDIS_HOST=localhost \
REDIS_PASSWORD=your_password \
DB_HOST=localhost \
DB_PASSWORD=your_password \
./bin/availability-engine

KAFKA_BROKERS=localhost:9092 \
CLICKHOUSE_DSN=clickhouse://default:password@localhost:9000/football_analytics \
./bin/analytics-pipeline

KAFKA_BROKERS=localhost:9092 \
VNPAY_HASH_SECRET=your_secret \
STRIPE_WEBHOOK_SECRET=whsec_... \
./bin/webhook-receiver

---

4. Kiểm tra services đang chạy

Mỗi service expose một health endpoint:

# document-worker
curl http://localhost:3010/health
# → {"status":"ok","uptime":"1m30s"}

# availability-engine (WebSocket + health)
curl http://localhost:3011/health

# analytics-pipeline
curl http://localhost:3012/health

# webhook-receiver
curl http://localhost:3013/health

Test WebSocket connection (availability-engine):

# Cần wscat: npm install -g wscat
wscat -c "ws://localhost:3011/ws?fieldId=field-123"
# Khi có booking event → server push: {"fieldId":"field-123","date":"2025-01-15","eventType":"booking.created"}

Test webhook (webhook-receiver):

# VNPay IPN test (signature sẽ invalid → trả RspCode 97, nhưng endpoint hoạt động)
curl -X POST http://localhost:3013/webhooks/vnpay/ipn \
  -d "vnp_TxnRef=TEST123&vnp_Amount=100000&vnp_ResponseCode=00&vnp_SecureHash=invalid"

# Stripe (cần Stripe CLI để tạo signature hợp lệ)
stripe trigger payment_intent.succeeded --webhook-endpoint http://localhost:3013/webhooks/stripe

---

5. Development workflow

Chạy tests

# Toàn bộ
go test ./...

# Một package cụ thể
go test ./internal/availability/checker/...

# Với coverage report
go test -race -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Lint

make lint
# hoặc
golangci-lint run ./...

Build tất cả binaries

make build
# Output: bin/document-worker, bin/availability-engine, ...

Thêm feature mới

Rule: Không tạo service mới — thêm vào đúng bucket.

├── Thêm generator mới (vd: Word doc)?   → internal/document/generator/
├── Thêm booking event mới?              → pkg/events/booking.go + consumer tương ứng
├── Thêm analytics metric?               → internal/analytics/transformer/ + writer
├── Thêm payment provider mới?          → internal/webhook/handler/ + verifier/

Khi NestJS thêm Kafka topic mới → phải update pkg/events/topics.go để đồng bộ.

---

6. Production deployment

Production deploy qua GitOps/ArgoCD (.github/workflows/cd.yml), giống hệt cách football-booking-backend-k3s deploy — không còn SSH + docker-compose trực tiếp lên VM nữa.

CI/CD tự động (GitHub Actions)

Push lên branch main sẽ tự động:

1. Detect service nào thay đổi (dựa trên cmd/, internal/, pkg/ changed files)
2. Build + push Docker image đa kiến trúc lên GHCR (ghcr.io/footballbookingteam100/go-<service>)
3. Commit image tag mới vào football-booking-gitops (envs/production/go-services/<service>.yaml)
4. ArgoCD (ApplicationSet football-booking-go-services) tự động phát hiện thay đổi và sync Deployment tương ứng lên K3s cluster (namespace football-booking)

Secrets cần thiết trong GitHub repo settings:

GITOPS_TOKEN   # PAT với quyền Contents: Read and write vào football-booking-gitops

GITHUB_TOKEN (build/push GHCR) đã có sẵn tự động, không cần tạo thêm.

Deploy thủ công / rollback

# Trigger sync ngay (không cần đợi ArgoCD tự poll ~3 phút)
argocd app sync go-document-worker

# Rollback bằng git (cách GitOps chuẩn)
git log --oneline -- envs/production/go-services/document-worker.yaml   # (trong repo gitops)
git revert <commit> && git push

Xem thêm football-booking-gitops/docs/argocd-guide.md.

---

7. Troubleshooting

Service không kết nối được Kafka

# Kiểm tra network
docker network inspect football-booking-network | grep -E "Name|IPv4"

# Kiểm tra Kafka broker accessible từ trong container
docker exec go-document-worker wget -qO- http://kafka:9092 2>&1 || echo "Kafka not reachable"

# Xem consumer group lag
docker exec kafka kafka-consumer-groups.sh \
  --bootstrap-server localhost:9092 \
  --group go-document-worker-group \
  --describe

WebSocket không nhận được update

# Kiểm tra consumer group đang consume
docker exec kafka kafka-consumer-groups.sh \
  --bootstrap-server localhost:9092 \
  --group go-availability-engine-group \
  --describe

# Xem logs hub
docker compose -f deployments/docker-compose.yml logs -f availability-engine

ClickHouse schema chưa được tạo

# Chạy migration thủ công
CLICKHOUSE_DSN=clickhouse://default:password@localhost:9000/football_analytics \
./scripts/migrate-clickhouse.sh

Traces không xuất hiện trong SigNoz

# Kiểm tra OTEL collector reachable
docker exec go-document-worker wget -qO- http://otel-collector:4317 2>&1

# Log OTEL error trong service
docker compose -f deployments/docker-compose.yml logs document-worker | grep -i otel

---

8. Port reference

Service	Port	Protocol	Accessible từ
document-worker	3010	HTTP /health	Docker network only
availability-engine	3011	HTTP + WebSocket	127.0.0.1 (api-gateway proxy)
analytics-pipeline	3012	HTTP /health	Docker network only
webhook-receiver	3013	HTTP POST	127.0.0.1 (Nginx routes VNPay/Stripe)