docs: add node-go base image design

2026-04-27 23:17:13 +07:00
parent 924f9a454f
commit cdaf343fc0
1 changed files with 122 additions and 0 deletions
@@ -0,0 +1,122 @@
+# Node + Go Base Image Design
+
+## Context
+
+Repository này đang duy trì các Docker base image nhỏ, tập trung cho từng nhu cầu riêng:
+
+- `docker-node.Dockerfile`: Node.js + Docker CLI + git
+- `node-python.Dockerfile`: Node.js + Python + git
+
+Mục tiêu của thay đổi này là bổ sung thêm một base image mới cho nhu cầu chạy dự án có cả Node.js và Go, đồng thời giữ cấu trúc và phong cách nhất quán với các image hiện có.
+
+## Goals
+
+- Thêm một Dockerfile mới cho image `node-go`
+- Giữ base image đồng nhất với repo: `node:lts-slim`
+- Cài Go từ tarball chính thức thay vì `apt`
+- Giữ image tối giản, chỉ cài thêm các gói hệ thống thật sự cần thiết
+- Cập nhật `README.md` để công bố image mới và các thành phần đi kèm
+
+## Non-Goals
+
+- Không thêm Docker CLI
+- Không thêm Python
+- Không pin cứng Node sang một major riêng ngoài `node:lts-slim`
+- Không thêm bộ công cụ build phụ ngoài những gì cần để tải và giải nén Go
+
+## Options Considered
+
+### Option 1: Cài Go từ Debian `apt`
+
+Ưu điểm:
+
+- Dockerfile ngắn hơn
+- Ít logic cài đặt hơn
+
+Nhược điểm:
+
+- Version Go thường chậm hơn bản phát hành chính thức
+- Khó dùng làm base image chung cho CI hoặc project cần Go mới hơn
+
+### Option 2: Cài Go từ tarball chính thức
+
+Ưu điểm:
+
+- Kiểm soát version Go rõ ràng bằng biến môi trường
+- Cập nhật nhanh hơn so với `apt`
+- Phù hợp hơn cho image nền dùng lại nhiều nơi
+
+Nhược điểm:
+
+- Dockerfile dài hơn một chút
+- Cần xử lý mapping kiến trúc để chọn đúng tarball
+
+## Chosen Design
+
+Chọn Option 2.
+
+Image mới sẽ:
+
+- dùng `FROM node:lts-slim`
+- cài `ca-certificates`, `curl`, `git`
+- khai báo `GO_VERSION`
+- xác định kiến trúc hiện tại từ `dpkg --print-architecture`
+- tải Go tarball phù hợp từ `https://go.dev/dl/`
+- giải nén vào `/usr/local/go`
+- thêm `/usr/local/go/bin` vào `PATH`
+- giữ `WORKDIR /app`
+
+## Implementation Details
+
+### Dockerfile mới
+
+Tạo file `node-go.Dockerfile` với cấu trúc gần giống các Dockerfile hiện có trong repo:
+
+1. `FROM node:lts-slim`
+2. Khai báo `ENV DEBIAN_FRONTEND=noninteractive`
+3. Cài các package hệ thống tối thiểu:
+   - `ca-certificates`
+   - `curl`
+   - `git`
+4. Khai báo `ARG GO_VERSION`
+5. Dùng `dpkg --print-architecture` để map:
+   - `amd64` -> `linux-amd64`
+   - `arm64` -> `linux-arm64`
+6. Tải tarball Go tương ứng, giải nén vào `/usr/local`
+7. Xóa file tạm và cache `apt`
+8. Khai báo `PATH=/usr/local/go/bin:${PATH}`
+9. Giữ `WORKDIR /app`
+
+### README
+
+`README.md` sẽ được cập nhật để thêm mục `node-go`, gồm:
+
+- image tag dự kiến theo naming convention hiện có
+- đường dẫn Dockerfile
+- danh sách phần mềm chính:
+  - Node.js kèm npm và yarn
+  - Go
+  - git
+
+## Verification Plan
+
+Sau khi implement:
+
+- kiểm tra cú pháp và nội dung Dockerfile mới
+- build thử image bằng `docker build -f node-go.Dockerfile .` nếu môi trường cho phép
+- xác nhận các binary chính tồn tại:
+  - `node --version`
+  - `go version`
+  - `git --version`
+
+## Risks
+
+- URL tải Go hoặc naming của tarball có thể đổi nếu `GO_VERSION` không hợp lệ
+- Mapping kiến trúc cần xử lý rõ để tránh build fail trên `arm64`
+- Nếu không pin `GO_VERSION`, output build có thể thay đổi theo thời gian; vì vậy nên khai báo version tường minh
+
+## Open Decisions Resolved
+
+- Chọn cài Go từ tarball chính thức thay vì `apt`
+- Giữ `node:lts-slim` để đồng nhất với repo hiện tại
+- Giữ image tối giản, không gộp thêm Docker CLI hoặc Python