بناء Docker

يُشحن المُنشئ كصورة Docker. تقوم مستودعات المحتوى بتشغيله لإنتاج HTML ثابت دون الحاجة لتثبيت Node.js أو Astro محلياً.

ملف Dockerfile

يستخدم docker/Dockerfile بناءً متعدد الخطوات على 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`	تتغير التبعيات نادراً؛ تخزين هذه الطبقة مؤقتاً يتجنب إعادة التنزيل عند كل بناء
2	`COPY . .`	الكود المصدري لإطار العمل
3	`rm -rf src/content/docs/*`	ينظف أي محتوى نائب بحيث يظهر فقط المحتوى المحقون
4	`COPY entrypoint.sh`	سكريبت تنسيق البناء

نقطة الدخول

يعمل docker/entrypoint.sh في كل مرة يبدأ فيها الحاوية. يقوم بتنفيذ هذه الخطوات بالترتيب:

الخطوة 1: تحديث التبعيات

npm install
npm update

يضمن أن حزمة القالب وجميع التبعيات في أحدث إصداراتها المتوافقة.

الخطوة 2: نسخ إعدادات القالب

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 من حزمة القالب. القالب هو المصدر الوحيد للحقيقة لإعدادات Astro — راجع البنية المعمارية لتصميم نظام القالب.

الخطوة 3: حقن المحتوى

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

ينسخ المحتوى المُربوط إلى مجلد مجموعة محتوى 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: في البيانات الوصفية الأمامية لملف index.mdx.

الخطوة 5: استخراج المسار الأساسي

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

يشتق مسار الموقع الأساسي من اسم مستودع GitHub (مثلاً، owner/my-docs يصبح /my-docs).

الخطوة 6: البناء

npm run build

يشغّل astro build، وينتج مخرجات ثابتة في /app/dist/.

الخطوة 7: نسخ المخرجات

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

ينسخ الموقع المبني إلى نقطة ربط المخرجات.

متغيرات البيئة

المتغير	القيمة الافتراضية	الوصف
`CONTENT_DIR`	`/content/docs`	مسار مجلد المحتوى المُربوط
`OUTPUT_DIR`	`/output`	المسار الذي يُنسخ إليه الموقع المبني
`DOCS_TITLE`	(يُستخرج من index.mdx)	عنوان الموقع المُمرر لإعدادات Astro
`DOCS_DESCRIPTION`	(يُستخرج من index.mdx)	وصف الموقع من البيانات الوصفية الأمامية
`DOCS_BASE`	(يُشتق من `GITHUB_REPOSITORY`)	المسار الأساسي للموقع (مثلاً، `/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 بعد البناء
`PDF_FILENAME`	`docs`	اسم ملف المخرجات لملف PDF المُنشأ
`LLMS_OPTIONAL_LINKS`	`[]`	مصفوفة JSON لعناوين URL للمواقع الفرعية لقسم Optional في `llms.txt`

الاستخدام المحلي

لبناء الوثائق محلياً باستخدام Docker:

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

يربط هذا مجلد docs/ المحلي كمحتوى ويكتب الموقع المبني إلى output/.

لمؤلفي المحتوى الذين يريدون سير عمل خادم تطوير مباشر، راجع المعاينة المحلية لمؤلفي المحتوى.

للمطورين: خادم التطوير المحلي

عند العمل على المُنشئ نفسه (المكونات، الإضافات، تكامل القالب)، يمكنك تشغيل خادم تطوير 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. يعمل الاستبدال الساخن للوحدات (HMR) مع تغييرات المكونات والإضافات.

سجل الصور

تُنشر الصورة في سجل حاويات GitHub:

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

يتم دفع وسمين عند كل بناء:

الوسم	الوصف
`latest`	أحدث بناء من فرع `main`
`<sha>`	معرّف SHA الكامل لإيداع Git للبناءات القابلة للتكرار

راجع التكامل المستمر/النشر المستمر والحوكمة لسير العمل الذي يبني وينشر الصورة.