Docker Build

ตัว builder จัดส่งในรูปแบบ Docker image โดย content repo จะเรียกใช้งานเพื่อสร้าง static HTML โดยไม่ต้องติดตั้ง Node.js หรือ Astro ในเครื่อง

Dockerfile

docker/Dockerfile ใช้การ build แบบหลายขั้นตอนบน node:24-alpine:

FROM node:24-alpine AS builder
WORKDIR /app

# Install deps (cached layer)
COPY package*.json ./
RUN npm ci

# Copy framework code
COPY . .

# Remove placeholder content
RUN rm -rf src/content/docs/*

COPY docker/entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]

กลยุทธ์เลเยอร์

เลเยอร์	สิ่งที่ทำ	เหตุผลที่แคชแยกกัน
1	COPY package*.json + npm ci	Dependencies ไม่ค่อยเปลี่ยนแปลง การแคชเลเยอร์นี้ช่วยหลีกเลี่ยงการดาวน์โหลดซ้ำทุกครั้งที่ build
2	COPY . .	ซอร์สโค้ดของ framework
3	rm -rf src/content/docs/*	ล้างเนื้อหา placeholder ออก เพื่อให้แสดงเฉพาะเนื้อหาที่ถูก inject เข้ามา
4	COPY entrypoint.sh	สคริปต์จัดการการ build

Entrypoint

docker/entrypoint.sh ทำงานทุกครั้งที่ container เริ่มต้น โดยดำเนินการตามขั้นตอนเหล่านี้ตามลำดับ:

ขั้นตอนที่ 1: อัปเดต Dependencies

npm install
npm update

ทำให้มั่นใจว่า theme package และ dependencies ทั้งหมดเป็นเวอร์ชันล่าสุดที่เข้ากันได้

ขั้นตอนที่ 2: คัดลอกการตั้งค่า Theme

cp /app/node_modules/@f5-sales-demo/docs-theme/astro.config.mjs /app/astro.config.mjs
cp /app/node_modules/@f5-sales-demo/docs-theme/src/content.config.ts /app/src/content.config.ts

คัดลอก astro.config.mjs และ content.config.ts จาก theme package โดย theme เป็นแหล่งข้อมูลเดียวที่เป็นต้นฉบับสำหรับการตั้งค่า Astro — ดู สถาปัตยกรรม สำหรับการออกแบบระบบ theme

ขั้นตอนที่ 3: Inject เนื้อหา

if [ -d "$CONTENT_DIR" ]; then
  cp -r "$CONTENT_DIR"/* /app/src/content/docs/
else
  echo "ERROR: No content found at $CONTENT_DIR"
  exit 1
fi

คัดลอกเนื้อหาที่ mount ไว้เข้าสู่ไดเรกทอรี content collection ของ Astro จะออกพร้อมข้อผิดพลาดหากไม่พบไดเรกทอรีเนื้อหา

ขั้นตอนที่ 4: ดึงชื่อเรื่อง

if [ -z "$DOCS_TITLE" ] && [ -f /app/src/content/docs/index.mdx ]; then
  DOCS_TITLE=$(grep -m1 '^title:' /app/src/content/docs/index.mdx | sed 's/title: *["]*//;s/["]*$//')
  export DOCS_TITLE
fi

หาก DOCS_TITLE ไม่ได้ตั้งค่าผ่านตัวแปรสภาพแวดล้อม จะดึงจากฟิลด์ title: ใน frontmatter ของ index.mdx

ขั้นตอนที่ 5: ดึง Base Path

if [ -z "$DOCS_BASE" ] && [ -n "$GITHUB_REPOSITORY" ]; then
  DOCS_BASE="/${GITHUB_REPOSITORY#*/}"
  export DOCS_BASE
fi

อนุมาน base path ของเว็บไซต์จากชื่อ GitHub repository (เช่น owner/my-docs จะกลายเป็น /my-docs)

ขั้นตอนที่ 6: Build

npm run build

เรียกใช้ astro build เพื่อสร้างผลลัพธ์แบบ static ใน /app/dist/

ขั้นตอนที่ 7: คัดลอกผลลัพธ์

if [ -d "$OUTPUT_DIR" ]; then
  cp -r /app/dist/* "$OUTPUT_DIR"/
fi

คัดลอกเว็บไซต์ที่ build แล้วไปยังจุด mount ผลลัพธ์

ตัวแปรสภาพแวดล้อม

ตัวแปร	ค่าเริ่มต้น	คำอธิบาย
CONTENT_DIR	/content/docs	เส้นทางไปยังไดเรกทอรีเนื้อหาที่ mount ไว้
OUTPUT_DIR	/output	เส้นทางที่เว็บไซต์ที่ build แล้วจะถูกคัดลอกไป
DOCS_TITLE	(ดึงจาก index.mdx)	ชื่อเว็บไซต์ที่ส่งไปยังการตั้งค่า Astro
DOCS_DESCRIPTION	(ดึงจาก index.mdx)	คำอธิบายเว็บไซต์จาก frontmatter
DOCS_BASE	(อนุมานจาก GITHUB_REPOSITORY)	Base path สำหรับเว็บไซต์ (เช่น /my-docs)
DOCS_SITE	(อนุมานจาก GITHUB_REPOSITORY_OWNER)	URL ของเว็บไซต์ที่ส่งไปยังการตั้งค่า Astro (เช่น https://<owner>.github.io)
GITHUB_REPOSITORY	(ตั้งค่าโดย GitHub Actions)	สตริง owner/repo ที่ใช้อนุมาน DOCS_BASE
GENERATE_PDF	false	เปิดใช้งานการสร้าง PDF หลัง build
PDF_FILENAME	docs	ชื่อไฟล์ผลลัพธ์สำหรับ PDF ที่สร้างขึ้น
LLMS_OPTIONAL_LINKS	[]	JSON array ของ URL เว็บไซต์ย่อยสำหรับส่วน Optional ของ llms.txt

การใช้งานในเครื่อง

ในการ build เอกสารในเครื่องโดยใช้ Docker:

docker run --rm \
  -v "$(pwd)/docs:/content/docs" \
  -v "$(pwd)/output:/output" \
  ghcr.io/f5-sales-demo/docs-builder:latest

คำสั่งนี้จะ mount ไดเรกทอรี docs/ ในเครื่องเป็นเนื้อหา และเขียนเว็บไซต์ที่ build แล้วไปยัง output/

สำหรับผู้เขียนเนื้อหาที่ต้องการเวิร์กโฟลว์ dev server แบบ live ดู การดูตัวอย่างในเครื่องสำหรับผู้เขียนเนื้อหา

นักพัฒนา: Dev Server ในเครื่อง

เมื่อทำงานกับตัว builder เอง (คอมโพเนนต์, ปลั๊กอิน, การรวม theme) คุณสามารถเรียกใช้ dev server ของ Astro โดยตรงโดยไม่ต้องใช้ Docker:

npm ci
cp node_modules/@f5-sales-demo/docs-theme/astro.config.mjs astro.config.mjs
cp node_modules/@f5-sales-demo/docs-theme/src/content.config.ts src/content.config.ts
# Copy some test content into the content collection
cp -r /path/to/test-content/* src/content/docs/
DOCS_TITLE="Dev Test" npx astro dev --host

เปิด http://localhost:4321 Hot module replacement (HMR) ทำงานได้สำหรับการเปลี่ยนแปลงคอมโพเนนต์และปลั๊กอิน

หมายเหตุ

astro.config.mjs และ content.config.ts มาจาก theme package และไม่ได้ถูกควบคุมเวอร์ชันใน repo นี้ คุณต้องคัดลอกจาก node_modules ก่อนเรียกใช้ dev server โดย entrypoint จะจัดการสิ่งนี้โดยอัตโนมัติใน Docker builds

หมายเหตุ

src/content/docs/ จะถูกล้างในขั้นตอนการ build image และถูก gitignore ไว้ วางเนื้อหาทดสอบที่นั่นด้วยตนเอง — มันจะไม่ถูก commit

Image Registry

Image ถูกเผยแพร่ไปยัง GitHub Container Registry:

ghcr.io/f5-sales-demo/docs-builder

มีการ push สองแท็กในทุกการ build:

แท็ก	คำอธิบาย
latest	การ build ล่าสุดจาก main
<sha>	SHA ของ Git commit แบบเต็มสำหรับการ build ที่ทำซ้ำได้

ดู CI/CD และการกำกับดูแล สำหรับ workflow ที่ build และเผยแพร่ image