Deployment & DevOps Guide

🚀 Deployment & DevOps Guide (คู่มือการขึ้นระบบและการจัดส่ง DevOps)

This guide details the containerization, continuous integration/deployment (CI/CD), security protocols, backup mechanisms, and disaster recovery procedures for SplitDee production servers.
เอกสารคู่มือระเบียบปฏิบัติในการขึ้นติดตั้งระบบคอนเทนเนอร์ (Docker), การทดสอบรวมรหัสและจัดส่งอัตโนมัติ (CI/CD) การสำรองข้อมูล และขั้นตอนฟื้นฟูหลังความเสียหายของเซิร์ฟเวอร์ SplitDee

---

🇹🇭 ภาษาไทย (สำหรับผู้ใช้งาน)

1. โครงสร้างตู้บริการคอนเทนเนอร์ (Docker Compose)

เซิร์ฟเวอร์ใช้งานโปรดักชันของ SplitDee ถูกควบคุมการรันผ่านคอนเทนเนอร์อิสระ 4 ตู้ เพื่อความง่ายในการโยกย้ายและจำลองสภาพแวดล้อม:

1. splitdee-backend: เว็บเซิร์ฟเวอร์หลังบ้านประมวลผล FastAPI
2. splitdee-db: เซิร์ฟเวอร์เก็บข้อมูลหลัก PostgreSQL 15
3. splitdee-redis: แคชความเร็วสูง Redis 7 ใช้จำโทเค็นและประมวล WebSocket แชทสด
4. splitdee-nginx: ด่านหน้าคอยทำหน้าที่กรองเน็ต รับ SSL และส่งต่อคำขอ (Proxy Pass) ไปในคอนเทนเนอร์หลังบ้าน

2. นโยบายการรันไมเกรชันตารางฐานข้อมูลในระบบจริง

• กฎเหล็ก: ห้ามสั่งสั่งรันสร้างตารางหรืออัปเดต Alembic Migrations บนโปรดักชันจริงโดยตรงเด็ดขาดหากยังไม่ผ่านการทดสอบบนระบบ Staging
• กระบวนการไมเกรชัน:
  1. คิวงาน CI/CD จะทดลองรันไมเกรชันตารางใส่ตู้จำลองทดสอบก่อน
  2. เมื่อผ่านเกณฑ์ สคริปต์ขึ้นเซิร์ฟเวอร์จะสั่งคำสั่งขยับเวอร์ชันตารางหลังบ้านดังนี้:
     docker compose exec backend alembic upgrade head
  3. บังคับให้อัปเดตตารางย้อนหลังเข้ากันได้เสมอ (Backward-Compatible) เพื่อไม่ให้บิลการชำระเงินของเพื่อนติดขัดขณะระบบกำลังอัปเดตเวอร์ชันฐานข้อมูล

3. ท่อรวมรหัสและขึ้นระบบอัตโนมัติ (CI/CD Pipeline - GitHub Actions)

• เมื่อนักพัฒนารวมโค้ดเข้ากิ่งหลัก main ➔ ระบบ GitHub Actions ทริกเกอร์เช็ก lints ตรวจหาสิทธิ์ และทดลองรันชุดทดสอบ Unit test/Integration test ทั้งหมด
• หากการทดสอบผ่าน ➔ ทำการแพ็คภาพ Docker Image ➔ โยนขึ้น Container Registry ประจำตัว ➔ ยิง SSH ไปที่ VPS เช่ารัน ➔ รันสคริปต์ deploy.sh เพื่อสั่งหยุดตู้บริการ ดึงตู้ตัวใหม่ รันไมเกรชันตาราง และเริ่มต้นแอปตัวใหม่ทันที

4. นโยบายสำรองข้อมูลและการกู้ภัยหลังพังเสียหาย (Backup & Disaster Recovery)

• การสำรองระบบ: ดำเนินการ Backup ข้อมูลตาราง PostgreSQL ออกมาเป็น SQL dump ทุกๆ 24 ชั่วโมง โดยไฟล์จะถูกเข้ารหัสระดับคีย์ลับ และอัปโหลดข้ามไปเก็บที่ AWS S3 ที่ปลอดภัยแยกจาก VPS โดยเก็บ Daily ย้อนหลัง 30 วัน, Weekly 12 สัปดาห์ และ Monthly 1 ปี
• แผนการกู้ภัยฉุกเฉิน: หากฐานข้อมูลสูญหายหรือเซิร์ฟเวอร์เสียหาย ➔ จัดซื้อ VPS ลินุกซ์เครื่องใหม่ ➔ ทำการติดตั้งระบบ Docker และโคลนโค้ด ➔ ดึงข้อมูล Backup ล่าสุดจาก AWS S3 ถอดรหัสยิงเข้าระบบฐานข้อมูล PostgreSQL ตู้ใหม่ ➔ รันคำสั่งเช็ก Alembic เพื่อยืนยันความพร้อม

---

🇬🇧 English (For AI Agents)

1. Containerization Architecture (Docker)

SplitDee runs in a multi-container environment orchestrated by Docker Compose:

• splitdee-backend: FastAPI app server running via Uvicorn.
• splitdee-db: PostgreSQL 15-alpine relational database server.
• splitdee-redis: Redis 7-alpine caching and pub/sub engine.
• splitdee-nginx: Nginx-alpine reverse proxy for SSL termination and static serving.

2. Production Database Migrations (Alembic)

• Rule: Never apply Alembic migrations directly in production without pre-testing on a staging environment.
• Migration Deployment:

  docker compose exec backend alembic upgrade head

• Make all database modifications backward-compatible. Add columns as nullable first to prevent runtime crashes.

3. CI/CD Pipeline (GitHub Actions)

1. Developer Push: Developer commits and pushes changes to main branch.
2. CI Check: Runs Python/Dart linters, tests, and validates minimum 80% coverage.
3. Build & Push: Packs Docker images and pushes to the container registry.
4. CD Deploy: Connects to Linux VPS via SSH, fetches the latest images, triggers Alembic migration, and restarts containers via deploy.sh.

4. Backup & Disaster Recovery Strategy

• Backup Policy: Full PostgreSQL SQL dump executed every 24 hours. Backups are encrypted via GPG and stored offsite in an AWS S3 bucket.
• Disaster Recovery Steps:
  1. Boot a fresh Linux VPS node.
  2. Clone the repository and configure production .env variables.
  3. Start infrastructure services: docker compose up -d db redis nginx.
  4. Download the latest backup database SQL dump from S3, decrypt, and import:

     gpg --decrypt backup.sql.gz.gpg | gunzip | docker compose exec -T db psql -U user -d splitdee

  5. Apply pending database migrations and boot the backend container: docker compose up -d backend.