base/docs/superpowers/specs/2026-04-27-node-go-design.md

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ữ GO_VERSION ở mức dễ đọc theo nhánh chính như 1.26
• 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 nhánh 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
• nếu GO_VERSION là major.minor, tải bản .0 tương ứng trong nhánh đó
• 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. Nếu GO_VERSION là major.minor, map sang .0 để tạo version tải cụ thể
7. Tải tarball Go tương ứng, giải nén vào /usr/local
8. Xóa file tạm và cache apt
9. Khai báo PATH=/usr/local/go/bin:${PATH}
10. 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 cần patch mới hơn trong cùng nhánh, phải nâng thủ công trong Dockerfile

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