เตรียมเครื่องสำหรับพัฒนา

ถ้าจะพัฒนาตัว TomeCMS เอง ให้รันเซิร์ฟเวอร์สำหรับพัฒนาของ Astro บนเครื่องของคุณ โดยมี PostgreSQL กับ SeaweedFS ซึ่งเป็นที่เก็บไฟล์แบบเดียวกับ S3 รันอยู่ใน Docker คำสั่งเดียวเตรียมทุกอย่างให้ครบ การตั้งค่าแบบนี้ใช้สำหรับพัฒนาเท่านั้น ถ้าจะเปิดเว็บให้ผู้อ่านจริง ให้ติดตั้งตามหน้าติดตั้งบน VPS

สิ่งที่ต้องมี

• Docker Desktop ที่เปิดทำงานอยู่
• Node.js 22.12 ขึ้นไป พร้อม npm
• Git
• พอร์ต 4321, 5432 และ 9000 บนเครื่องที่ยังว่างอยู่

ตรวจเครื่องมือหลักได้ด้วยคำสั่งเหล่านี้

node --version
npm --version
docker version
docker compose version

บน macOS

macOS คือทางหลักที่ใช้พัฒนา และเป็นทางที่ผ่านการตรวจแล้ว ในโฟลเดอร์ของโปรเจกต์ให้รัน

npm run dev:macos

สคริปต์ช่วยจะทำตามขั้นตอนเหล่านี้ และหยุดพร้อมข้อความทันทีที่ขั้นไหนไม่ผ่าน

1. ตรวจว่ากำลังรันบน macOS มี node, npm และ docker ติดตั้งไว้ และ Docker Desktop เปิดอยู่
2. รัน npm ci ถ้ายังไม่ได้ติดตั้งแพ็กเกจ
3. ตรวจว่าพอร์ตทั้งสามว่าง และสร้าง .env.local ถ้ายังไม่มี โดยใส่ค่าลับที่สุ่มขึ้นใหม่กับที่อยู่สำหรับเครื่องนี้ และตั้งให้คุณอ่านได้คนเดียว
4. เปิด PostgreSQL กับ SeaweedFS แล้วรอจนทั้งสองตัวพร้อม SeaweedFS สร้าง bucket สำหรับไฟล์สื่อเองตอนเริ่มทำงาน
5. ปรับฐานข้อมูลตาม migration
6. พิมพ์ที่อยู่ของตัวติดตั้งกับโทเค็นการติดตั้งออกมา
7. เปิด Astro

ไม่ต้องมีบัญชีที่เก็บไฟล์หรือไฟล์ license ใด ๆ เปิด http://localhost:4321/install แล้วทำตามตัวช่วยตั้งค่าครั้งแรก ซึ่งจะถามโทเค็นการติดตั้ง ถ้าต้องการดูโทเค็นอีกครั้ง

grep '^TOME_CMS_INSTALL_TOKEN=' .env.local

เปิดเทอร์มินัลนั้นทิ้งไว้ระหว่างทำงาน กด Ctrl+C เพื่อหยุด Astro ส่วน PostgreSQL กับ SeaweedFS จะยังรันอยู่ใน Docker จนกว่าคุณจะสั่งหยุด

npm run infra:down

คำสั่งนี้ลบ container ทั้งสองตัวออก แต่ฐานข้อมูลกับไฟล์ยังอยู่ใน volume ของ Docker และจะกลับมาเมื่อรันสคริปต์ช่วยครั้งถัดไป

.env.local เก็บค่าลับของเครื่องคุณ และ .gitignore ของ repository ไม่รวมไฟล์นี้ไว้

เมื่อสคริปต์ช่วยหยุดกลางทาง

ข้อความ	ต้องทำอะไร
Error: Docker Desktop is not running.	เปิด Docker Desktop แล้วรันสคริปต์ช่วยอีกครั้ง
Port 5432 is unavailable.	มีโปรแกรมอื่นใช้พอร์ตนั้นอยู่ ให้หยุดโปรแกรมนั้นแล้วรันสคริปต์ช่วยอีกครั้ง ข้อความจะบอกหมายเลขของพอร์ตที่ไม่ว่าง ไม่ว่าจะเป็นพอร์ตไหนในสามพอร์ต
Existing .env.local needs updates; rerun with --force to merge values while preserving secrets.	โค้ดรุ่นใหม่ต้องใช้ค่าที่ .env.local ของคุณยังไม่มี เปิดดูไฟล์ก่อน แล้วรัน npm run dev:macos -- --force
Set .env.local permissions to 0600 before continuing.	คนอื่นอ่านไฟล์นี้ได้ ให้รัน chmod 600 .env.local หรือรันสคริปต์ช่วยพร้อม -- --force ซึ่งจะเขียนไฟล์กลับให้คุณอ่านได้คนเดียว

--force รวมค่าตั้งต้นใหม่เข้าไปใน .env.local โดยเก็บค่าลับทุกตัวที่มีอยู่แล้วไว้ตามเดิม

บน Windows

Windows เป็นทางรองสำหรับพัฒนา ใช้ Windows 11 ที่มี Docker Desktop, Node.js 22.12 ขึ้นไป, npm, Git และ PowerShell ใน PowerShell ให้รันคำสั่งนี้ในโฟลเดอร์ของโปรเจกต์

npm run dev:windows

สคริปต์ช่วยตรวจเครื่องมือชุดเดียวกัน แล้วรัน scripts/bootstrap-core.mjs ตัวเดียวกับบน macOS บน Windows สคริปต์จะเรียก npm ผ่าน npm.cmd และข้ามการตรวจว่า .env.local อ่านได้เฉพาะคุณ เพราะ Node บน Windows รายงานว่าไฟล์ที่เขียนได้ทุกไฟล์คนอื่นอ่านได้ด้วย ทางนี้ยังไม่เคยลองบนเครื่อง Windows จริง ถ้าสคริปต์ช่วยหยุดที่ขั้น migration ให้รัน npm run db:migrate แล้วตามด้วย npm run dev เอง โทเค็นอยู่ใน .env.local

แยกฐานข้อมูลกับที่เก็บไฟล์ออกจาก Astro

สคริปต์ช่วยจบด้วยการรัน Astro ในเทอร์มินัลเดียวกับที่เริ่ม ถ้าอยากแยกสองส่วนนี้ออกจากกัน เพื่อจะเริ่ม Astro ใหม่ได้โดยไม่ต้องเตรียมทุกอย่างซ้ำ ให้รันแต่ละขั้นเอง ติดตั้งแพ็กเกจด้วย npm ci ก่อน แล้วรัน

npm run bootstrap:core
npm run dev

bootstrap:core คือสคริปต์ช่วยที่ตัดสองขั้นแรกกับขั้นสุดท้ายออก คำสั่งนี้ตรวจพอร์ต สร้าง .env.local ถ้ายังไม่มี เปิด PostgreSQL กับ SeaweedFS ปรับฐานข้อมูลตาม migration พิมพ์โทเค็น แล้วจบด้วย Start the application with npm run dev. ฐานข้อมูลกับที่เก็บไฟล์ยังรันอยู่ใน Docker ต่อไป เทอร์มินัลนั้นจึงว่างให้ใช้ต่อ ส่วน npm run dev รัน Astro ในเทอร์มินัลที่คุณสั่ง และจะหยุดแล้วเริ่มใหม่ที่นั่นกี่ครั้งก็ได้

คำสั่งเหล่านี้ใช้กับการตั้งค่าชุดเดียวกัน

คำสั่ง	ทำอะไร
npm run infra:up	เปิด PostgreSQL กับ SeaweedFS ด้วยค่าใน .env.local แล้วรอจนพร้อม
npm run db:migrate	ปรับฐานข้อมูลตาม migration ที่ยังไม่ได้รัน
npm run media:cleanup	แสดงรายการการจองอัปโหลดที่หมดอายุ และไฟล์ที่ลบไม่สำเร็จ ถ้าใส่ -- --execute คำสั่งจะให้พิมพ์ยืนยันก่อน แล้วจึงลบออก
npm run infra:down	หยุด PostgreSQL กับ SeaweedFS และลบ container ของทั้งสองตัว โดยเก็บข้อมูลไว้