From 22fdd37869dd75056aa1b3f99f8ab91b6fdf6dc7 Mon Sep 17 00:00:00 2001 From: Bkk1234 Date: Mon, 23 Nov 2026 01:57:25 +0700 Subject: [PATCH] docs: Docker run instructions, env table, and compose deploy topology --- AGENTS.md | 17 +++++++++++++++++ SYSTEM-DESIGN.md | 17 +++++++++-------- service/README.md | 36 ++++++++++++++++++++++++++++++++++++ 3 files changed, 62 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4e2c3c1..e902acb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -47,6 +47,23 @@ node --test tests/*.test.mjs - สคีมา DB: `service/db/001_init.sql` · สัญญา API: `service/openapi.yaml` - ห้าม commit `service/.env` (มีรหัส DB) +### Docker (web + API + PostgreSQL) — พอร์ตมาจาก `.env` + +```bash +cp .env.example .env # ตั้ง DB_PASSWORD ก่อน (compose ไม่ start ถ้าว่าง) +docker compose build # ครั้งแรก ~5 นาที (Julia Pkg.instantiate) +docker compose up -d +docker compose ps # รอ Up (healthy) ทั้ง 3 บริการ +curl -s http://127.0.0.1:8095/healthz # ok +curl -s http://127.0.0.1:8000/api/v1/health # database.connected = true +docker compose down # หยุด · เพิ่ม -v ถ้าต้องล้างฐานข้อมูล +``` + +- `WEB_CONTAINER_PORT`/`WEB_HOST_PORT` · `API_CONTAINER_PORT`/`API_HOST_PORT` · `DB_HOST_PORT` = ตัวแปรเดียวที่ต้องแก้ +- `deploy/nginx.conf.template` ใช้ `${WEB_CONTAINER_PORT}` (nginx image envsubst ให้เอง) และ proxy `/api/` → `api:${API_CONTAINER_PORT}` +- แก้ไฟล์ static = ต้อง `docker compose up -d --build` (COPY เข้า image ไม่ใช่ mount) +- รายละเอียดทุกตัวแปร: `service/README.md` §6 + ## อัปเดตเวอร์ชัน — ห้ามแก้มือทีละไฟล์ ```bash diff --git a/SYSTEM-DESIGN.md b/SYSTEM-DESIGN.md index 5a6d470..ff638ef 100644 --- a/SYSTEM-DESIGN.md +++ b/SYSTEM-DESIGN.md @@ -259,17 +259,18 @@ irrcal/ ## 10. Deploy ``` -[nginx :443] - / → dist/ (Vue build · hash router จึงไม่ต้อง rewrite) - /docs/ → dist/docs/ (ตำรา 10 บท) - /api/ → proxy_pass http://127.0.0.1:8000 -[julia service] systemd unit farm-api.service · FARM_API_HOST=127.0.0.1 -[postgresql] psql -f service/db/001_init.sql · seed ETo ด้วย tools/seed_eto.py +[docker compose] (ตอนนี้) + web nginx:alpine listen ${WEB_CONTAINER_PORT} · root /app · /api/ → api + api julia:1.13-bookworm FARM_API_HOST=0.0.0.0 · FARM_API_PORT=${API_CONTAINER_PORT} + db postgres:17-alpine volume pgdata · service/db/001_init.sql (ครั้งแรก) + +[แบบเดิม ไม่ใช้แล้ว] nginx บน host + systemd unit + postgres ในเครื่อง ``` -- prod ตั้ง `FARM_CORS_ORIGIN=https://<โดเมน>` (ไม่ใช่ `*`) +- พอร์ตทุกตัวมาจาก `.env` ที่ราก repo (`.env.example` ขึ้น git, `.env` ไม่ขึ้น) +- prod: `FARM_CORS_ORIGIN` ใส่ origin จริง และไม่ต้อง publish `DB_HOST_PORT`/`API_HOST_PORT` ออกนอก - ถ้า API ตาย เว็บยังคำนวณได้ด้วย `js-offline` — deploy จึงไม่ใช่ single point of failure -- `service/.env` อยู่นอก git เสมอ · `.env.example` มีชื่อคีย์เท่านั้น +- `service/.env` (แบบรันบน host) และ `.env` (แบบ compose) อยู่นอก git เสมอ --- diff --git a/service/README.md b/service/README.md index f4a3c69..dbe1447 100644 --- a/service/README.md +++ b/service/README.md @@ -57,6 +57,35 @@ julia --project=service service/test/runtests.jl # ฝั่ง Julia node --test tests/*.test.mjs # ฝั่ง JS (รวม golden vectors) ``` +## 6) รันด้วย Docker (เว็บ + API + PostgreSQL พร้อมกัน) + +พอร์ตทุกตัวมาจาก `.env` ที่ราก repo — ไม่มีเลขพอร์ตฝังในไฟล์ config + +```bash +cp .env.example .env # แล้วตั้ง DB_PASSWORD (compose ไม่ยอม start ถ้าว่าง) +docker compose build +docker compose up -d +docker compose ps # รอจนเห็น Up (healthy) +curl -s http://127.0.0.1:8095/healthz # ok +curl -s http://127.0.0.1:8000/api/v1/health # database.connected = true +``` + +| ตัวแปรใน `.env` | ค่าเริ่มต้น | ใช้ทำอะไร | +|---|---|---| +| `WEB_CONTAINER_PORT` | 8080 | พอร์ตที่ nginx ฟังในคอนเทนเนอร์ (แทนค่าใน `deploy/nginx.conf.template`) | +| `WEB_HOST_PORT` | 8095 | พอร์ตที่เปิดออกเครื่อง (8080 บนเครื่องนี้ถูกใช้อยู่) | +| `API_CONTAINER_PORT` | 8000 | พอร์ตที่ Julia ฟังในคอนเทนเนอร์ (`FARM_API_PORT`) + ปลายทางของ `/api/` | +| `API_HOST_PORT` | 8000 | พอร์ตที่เปิด API ออกเครื่อง (ใช้ตรวจ/ทดสอบตรง) | +| `DB_HOST_PORT` | 5433 | พอร์ต PostgreSQL ออกเครื่อง (5432 ในเครื่องมีอยู่แล้ว) | +| `DB_NAME` / `DB_USER` / `DB_PASSWORD` | farm_planning / postgres / ว่าง | ฐานข้อมูล (สคีมาจาก `service/db/001_init.sql` ตอนสร้างครั้งแรก) | +| `FARM_PERSIST_RUNS` | true | false = ไม่บันทึก `calculation_runs` | +| `FARM_CORS_ORIGIN` | `*` | prod ให้ใส่ origin จริง | + +- เว็บเรียก API ผ่าน path เดียวกัน (`/api/...` → proxy ไปคอนเทนเนอร์ `api`) จึงไม่ติด CORS +- ไฟล์ static ถูก COPY เข้า image — แก้หน้าเว็บแล้วต้อง `docker compose up -d --build` +- ฐานข้อมูลอยู่ใน named volume `pgdata` · ล้างทั้งหมด: `docker compose down -v` + + ## ไฟล์ ``` @@ -67,7 +96,14 @@ service/ ├── db/001_init.sql สคีมา (calculation_runs, provinces, eto_monthly, view) ├── test/runtests.jl ทดสอบด้วย golden vectors ชุดเดียวกับ JS ├── openapi.yaml สัญญา API +├── Dockerfile image ของ API (julia:1.13-bookworm + libpq5) └── .env.example ค่าที่ต้องตั้ง (คัดลอกเป็น .env เอง) + +ราก repo/ +├── Dockerfile image เว็บ static (nginx:alpine) +├── docker-compose.yml web + api + db (พอร์ตจาก .env) +├── deploy/nginx.conf.template listen ${WEB_CONTAINER_PORT} + proxy /api/ +└── .env.example พอร์ต/ฐานข้อมูลของ compose ``` ## กติกา