การตั้งค่า

TomeCMS อ่านการตั้งค่าจากตัวแปรสภาพแวดล้อม (environment variable) ในการติดตั้งแบบ managed ค่าทั้งหมดอยู่ในไฟล์ /etc/tome-cms/tome-cms.env ซึ่งตัวติดตั้งเขียนไว้ และอ่านได้เฉพาะ root กับกลุ่มของตัวอัปเดต ในการติดตั้งแบบ build จากซอร์สโค้ด ค่าทั้งหมดอยู่ในไฟล์ .env.local ในโฟลเดอร์โค้ด สคริปต์ deploy เขียนไฟล์นี้ตอนรันครั้งแรก และตั้งสิทธิ์ให้เจ้าของไฟล์อ่านได้คนเดียว หน้าติดตั้งบน VPS อธิบายขั้นตอนไว้ทั้งสองแบบ ส่วนไฟล์ .env.example ใน repository มีชื่อตัวแปรชุดเดียวกันพร้อมค่าตัวอย่าง

แอปและสคริปต์อ่านค่าจากที่ไหน

• คอนเทนเนอร์ของแอปอ่าน /etc/tome-cms/tome-cms.env ในการติดตั้งแบบ managed และอ่าน .env.local ในการติดตั้งแบบ build จากซอร์สโค้ด แต่ Compose จะกำหนดค่าสองตัวทับเองเสมอ ไม่ว่าในไฟล์จะเขียนไว้อย่างไร ได้แก่ DATABASE_URL ซึ่งชี้ไปที่ PostgreSQL ที่มากับชุดติดตั้งภายในเครือข่ายของ Compose และ NODE_ENV ซึ่งเป็น production
• สคริปต์ที่สั่งด้วย npm run เช่น db:migrate, backup และ admin:reset-installation โหลด .env.local ถ้ามีไฟล์นี้อยู่
• npm run admin:recover ซึ่งเป็นคำสั่งในหน้ากลับเข้าหน้าผู้ดูแล อ่านไฟล์ที่ TOME_CMS_ENV_FILE ระบุ ถ้าไม่ได้ระบุจะอ่าน .env.local และถ้าไม่มีจึงอ่าน /etc/tome-cms/tome-cms.env

ทั้งสองไฟล์เขียนทุกค่าไว้ในเครื่องหมายคำพูดเดี่ยว เช่น S3_REGION='us-east-1' เวลาแก้ไฟล์ให้เขียนแบบเดียวกัน

ตัวแปรที่แอปอ่าน

ตัวแปร	จำเป็นไหม	ค่าเริ่มต้น	ใช้ทำอะไร
NODE_ENV	ไม่บังคับ	development	development, test หรือ production ถ้าเป็น production จะเปิดกติกาเรื่อง HTTPS ที่อธิบายไว้ด้านล่าง
DATABASE_URL	ต้องมี	ไม่มี	connection string ของ PostgreSQL ขึ้นต้นด้วย postgres:// หรือ postgresql://
DATABASE_POOL_MAX	ไม่บังคับ	10	จำนวนการเชื่อมต่อฐานข้อมูลที่แอปเปิดค้างไว้ได้มากที่สุด ตั้งได้ตั้งแต่ 1 ถึง 50
DATABASE_CONNECTION_TIMEOUT_MS	ไม่บังคับ	5000	เวลาที่รอการเชื่อมต่อฐานข้อมูล หน่วยเป็นมิลลิวินาที ตั้งได้ตั้งแต่ 100 ถึง 60000
DATABASE_QUERY_TIMEOUT_MS	ไม่บังคับ	30000	เวลาที่ query หนึ่งครั้งรันได้นานที่สุด หน่วยเป็นมิลลิวินาที ตั้งได้ตั้งแต่ 100 ถึง 3600000 ค่านี้คุมทั้งฝั่ง driver และ statement timeout ของ PostgreSQL เอง ถ้ามี migration ที่ใช้เวลานานให้เพิ่มค่านี้
TOME_CMS_PUBLIC_URL	ต้องมี	ไม่มี	origin ของ CMS เช่น https://cms.example.com ห้ามมี path, query หรือ fragment ต่อท้าย
TOME_CMS_INSTALL_TOKEN	ต้องมี	ไม่มี	token ที่ตัวช่วยตั้งค่าครั้งแรกขอให้กรอก ยาวอย่างน้อย 32 ตัวอักษร
BETTER_AUTH_SECRET	ต้องมี	ไม่มี	ค่าลับที่ Better Auth (ส่วนที่ดูแลการเข้าสู่ระบบ) ใช้เซ็น session ยาวอย่างน้อย 32 ตัวอักษร
TOME_CMS_CONTEXT_SECRET	ต้องมี	ไม่มี	ใช้เซ็นขั้นตอนระยะสั้นระหว่างติดตั้งและกู้คืนบัญชี เซ็น cursor ของหน้าผลลัพธ์ใน API เป็นกุญแจของระบบจำกัดอัตราการเรียก และใช้เข้ารหัสค่าลับในการตั้งค่าของปลั๊กอิน ยาวอย่างน้อย 32 ตัวอักษร
TOME_CMS_RECOVERY_PEPPER	ต้องมี	ไม่มี	ใช้ hash รหัสกู้คืนของเจ้าของเว็บ ยาวอย่างน้อย 32 ตัวอักษร
S3_ENDPOINT	ต้องมี	ไม่มี	origin ของ object storage แอปเข้าถึง bucket ผ่านที่อยู่นี้ และเบราว์เซอร์อัปโหลดไฟล์มาที่นี่
S3_REGION	ไม่บังคับ	us-east-1	region ของ bucket
S3_ACCESS_KEY_ID	ต้องมี	ไม่มี	access key ของ object storage
S3_SECRET_ACCESS_KEY	ต้องมี	ไม่มี	secret key ของ object storage ยาวอย่างน้อย 8 ตัวอักษร
S3_BUCKET	ต้องมี	ไม่มี	ชื่อ bucket ยาว 3 ถึง 63 ตัว ใช้ได้เฉพาะตัวพิมพ์เล็ก ตัวเลข จุด และขีดกลาง และต้องขึ้นต้นกับลงท้ายด้วยตัวอักษรหรือตัวเลข สคริปต์ deploy ใช้ชื่อ tomecms-media
S3_FORCE_PATH_STYLE	ไม่บังคับ	true	true ใส่ชื่อ bucket ไว้ใน path ของที่อยู่ ส่วน false ใส่ไว้ในชื่อโฮสต์ ถ้าใช้ SeaweedFS ที่มากับชุดติดตั้งให้คงไว้เป็น true
MEDIA_PUBLIC_URL	ต้องมี	ไม่มี	ที่อยู่ที่ผู้อ่านใช้โหลดไฟล์ ห้ามมี query หรือ fragment ถ้าไม่กำหนด สคริปต์ deploy จะประกอบให้จาก S3_ENDPOINT กับชื่อ bucket
TOME_CMS_FRONTEND_MODE	ไม่บังคับ	bundled	bundled ให้บริการหน้าเว็บสาธารณะด้วย ส่วน headless ตอบ 404 ให้หน้าเว็บเหล่านั้น แต่หน้าแอดมินและ API ยังใช้ได้
TOME_CMS_UPDATE_MODE	ไม่บังคับ	check-only	check-only หรือ managed สคริปต์ deploy เขียน check-only ทุกครั้ง ค่า managed เขียนได้โดยตัวติดตั้งแบบ managed เท่านั้น ตั้งแต่ 1.0.0 ขึ้นไป
TOME_CMS_UPDATER_SOCKET	ไม่บังคับ	/run/tome-cms/updater.sock	socket ของ service ตัว updater ในการติดตั้งแบบ managed ต้องเป็นไฟล์ .sock ที่อยู่ใน /run/tome-cms/ โดยตรง
TOME_CMS_COUNTRY_HEADER	ไม่บังคับ	cf-ipcountry	ชื่อ header ที่ CDN ใส่ประเทศของผู้อ่านมาให้ ใช้ในหน้าสถิติ ชื่อต้องมีแต่ตัวอักษร ตัวเลข และขีดกลาง ถ้ามีอย่างอื่นปน ระบบจะกลับไปใช้ cf-ipcountry
TOME_CMS_GEOIP_PATH	ไม่บังคับ	data/geoip/dbip-country-lite.mmdb	ไฟล์ฐานข้อมูลประเทศ DB-IP Lite ใช้เมื่อ header ไม่ได้บอกประเทศมา path นี้เป็น path ภายในคอนเทนเนอร์ของแอป ให้วางไฟล์ไว้ใน data/geoip/ ในโฟลเดอร์โค้ด แล้วรัน ./scripts/deploy-vps.sh อีกครั้ง สคริปต์จะ build ไฟล์นี้เข้าไปใน image

ถ้าขาดค่าที่ต้องมี หรือมีค่าที่อยู่นอกขอบเขตข้างต้น TomeCMS จะไม่ให้บริการเว็บ และ /health/ready จะไม่รายงานว่าพร้อม ค่าสองตัวของสถิติเป็นข้อยกเว้น ถ้าไม่มีฐานข้อมูลประเทศ หน้าสถิติจะแสดงประเทศเป็นไม่ทราบ แต่ส่วนอื่นของเว็บยังทำงานตามปกติ

ตัวแปรที่ Compose และเครื่องมือบรรทัดคำสั่งอ่าน

แอปไม่ได้อ่านค่ากลุ่มนี้ Compose และสคริปต์ต่าง ๆ เอาค่าไปจาก .env.local หรือจาก shell ของคุณ

ตัวแปร	จำเป็นไหม	ค่าเริ่มต้น	ใช้ทำอะไร
POSTGRES_PASSWORD	ต้องมี	ไม่มี	รหัสผ่านของ PostgreSQL ที่มากับชุดติดตั้ง สคริปต์ deploy สร้างให้และใช้ประกอบ DATABASE_URL ยาวอย่างน้อย 8 ตัว ใช้ได้เฉพาะตัวอักษร ตัวเลข _ และ -
APP_PORT	ไม่บังคับ	4321	พอร์ตบน 127.0.0.1 ที่แอปรับคำขอ ให้ชี้ reverse proxy มาที่พอร์ตนี้
POSTGRES_PORT	ไม่บังคับ	5432	พอร์ตบน 127.0.0.1 ของ PostgreSQL ที่มากับชุดติดตั้ง
S3_PORT	ไม่บังคับ	9000	พอร์ตบน 127.0.0.1 ที่ SeaweedFS ที่มากับชุดติดตั้งรับคำขอ S3 ให้ชี้ proxy ของ origin มีเดียมาที่พอร์ตนี้
TOME_CMS_ENV_FILE	ไม่บังคับ	.env.local ถ้าไม่มีจึงใช้ /etc/tome-cms/tome-cms.env	ไฟล์ที่ npm run admin:recover อ่านค่าตั้งค่า

เมื่อเป็น production ต้องใช้ HTTPS

เมื่อ NODE_ENV เป็น production ค่า TOME_CMS_PUBLIC_URL, S3_ENDPOINT และ MEDIA_PUBLIC_URL ต้องขึ้นต้นด้วย https:// และอยู่บนโฮสต์สาธารณะที่เบราว์เซอร์เข้าถึงได้ TomeCMS ไม่รับที่อยู่ IP แบบ private หรือแบบสงวนไว้ localhost และชื่อที่ลงท้ายด้วย .local, .internal, .lan, .test, .example รวมถึงชื่อสำหรับใช้งานพิเศษอื่น ๆ สำหรับ TOME_CMS_PUBLIC_URL ให้ใช้ชื่อโฮสต์แทน IP เพราะ passkey ไม่รับที่อยู่ IP แม้จะเป็น IP สาธารณะก็ตาม สคริปต์ deploy ตรวจกติกาชุดเดียวกันนี้ก่อนเขียนไฟล์ใด ๆ

ถ้าไม่ได้อยู่ใน production ที่อยู่ HTTP ธรรมดาที่เข้าสู่ระบบได้มีแค่ http://localhost เท่านั้น

ใช้ object storage ของผู้ให้บริการอื่น

SeaweedFS ที่มากับชุดติดตั้งทำงานเป็นโหนดเดียว ซึ่งเหมาะกับ VPS เครื่องเดียว ถ้าต้องการ high availability หรือต้องการมากกว่าหนึ่งโหนด ให้ชี้ค่า S3_* ชุดเดิมและ MEDIA_PUBLIC_URL ไปที่ object storage ภายนอก

เบราว์เซอร์อัปโหลดไฟล์เข้า bucket โดยตรง storage ภายนอกจึงต้องมีกฎ CORS สำหรับ origin ของเว็บ ซึ่งก็คือค่าของ TOME_CMS_PUBLIC_URL กฎนี้ต้องอนุญาต PUT พร้อม header content-type, x-amz-checksum-sha256 และ content-disposition ตัวสุดท้ายบอกชื่อไฟล์เอกสารและวิธีเปิดไฟล์ และรวมอยู่ในลายเซ็นของการอัปโหลดด้วย ถ้าเขียนในรูปแบบที่ AWS S3 ใช้ กฎจะหน้าตาแบบนี้

[
  {
    "AllowedOrigins": ["https://cms.example.com"],
    "AllowedMethods": ["PUT"],
    "AllowedHeaders": ["content-type", "x-amz-checksum-sha256", "content-disposition"]
  }
]

SeaweedFS ที่มากับชุดติดตั้งตั้งค่า CORS ให้ origin ของเว็บไว้แล้ว และไม่เปิดให้ origin อื่นเลย

การเปลี่ยนค่า

แก้ .env.local ในโฟลเดอร์โค้ด แล้วรัน ./scripts/deploy-vps.sh อีกครั้ง สคริปต์จะคงทุกค่าในไฟล์ไว้ รวมถึงบรรทัดที่คุณเพิ่มเอง แล้วเปิดแอปด้วยค่าเหล่านั้น มีแค่ NODE_ENV, TOME_CMS_UPDATE_MODE และ TOME_CMS_UPDATER_SOCKET ที่สคริปต์กำหนดเองทุกครั้ง ค่าที่สคริปต์รับจาก shell มีแค่ค่าที่ต้องมี ค่าปรับแต่งฐานข้อมูลสามตัว และพอร์ตสามตัว ถ้าค่าที่คุณ export ไม่ตรงกับในไฟล์ สคริปต์จะหยุดและให้รันใหม่ด้วย --force

เมื่อติดตั้งเว็บเสร็จแล้ว อย่าเปลี่ยนค่าลับ ถ้าเปลี่ยน TOME_CMS_RECOVERY_PEPPER รหัสกู้คืนที่บันทึกไว้ทุกชุดจะใช้ไม่ได้ และถ้าเปลี่ยน TOME_CMS_CONTEXT_SECRET ค่าลับในการตั้งค่าของปลั๊กอินจะอ่านไม่ออก ชุดสำรองข้อมูลไม่ได้เก็บค่าลับไว้ จึงควรเก็บสำเนา .env.local ไว้ในที่ปลอดภัย แยกจากชุดสำรอง

สิ่งที่ห้าม commit

ห้าม commit .env.local, ข้อมูลรับรองการเข้าถึง (credential), ไฟล์ dump ของฐานข้อมูล และชุดสำรองของ object storage ไฟล์ .gitignore ของ repository กัน .env.local ไว้แล้ว และสคริปต์ deploy เขียนไฟล์นี้ให้เจ้าของไฟล์อ่านได้คนเดียว