# ==============================================================================
# ConvertX-CN Docker Compose 教學版範例
#
# 📚 這份範例的設計理念：
#    - 刻意保留完整註解，讓第一次用 Docker 的人也能成功部署
#    - 每個設定都有說明其用途與風險
#    - 如果你是 Docker 老手，可以自行精簡
#
# 🎉 這是完整版 image，已內建所有轉換依賴：
#    - LibreOffice (headless) - 文件轉換
#    - TexLive Full - LaTeX 完整版（含 CJK、阿拉伯、希伯來語支援）
#    - Tesseract OCR + 中日韓英德法語言包
#    - CJK 字型（Noto CJK、標楷體、微軟核心字型）
#    - Pandoc、FFmpeg、ImageMagick、Calibre 等所有轉換器
#
# ✅ 使用者不需要自己寫 Dockerfile
# ✅ 直接 docker compose up -d 即可使用
#
# ⚠️ 部署前必做：
#    1. 先建立 data 資料夾（見 README.md 步驟 2）
#    2. 修改 JWT_SECRET 為你自己的隨機字串
#
# ==============================================================================
# 🆕 API Server（選用功能）
# ==============================================================================
#
# ConvertX 現在提供獨立的 REST / GraphQL API Server！
#
# ⚠️ 預設不啟動 API Server
#    一般使用者只需要 Web UI，不需要啟動 API
#
# 🚀 如何啟用 API Server？
#    使用 profile 功能：
#
#    # 只啟動 Web UI（預設行為）
#    docker compose up -d
#
#    # 同時啟動 Web UI + API Server
#    docker compose --profile api up -d
#
# 📖 API 文件請參考：api-server/README.md
#
# ==============================================================================

services:
  convertx:
    # =========================================================================
    # 映像檔設定
    # =========================================================================
    # convertx-cn 是完整版，已內建所有轉換工具
    # ⚠️ 首次下載約 4-6 GB，請耐心等待
    image: convertx/convertx-cn:latest

    # 容器名稱，方便識別與管理
    container_name: convertx-cn

    # 重啟策略：
    # - unless-stopped：除非手動停止，否則自動重啟（推薦）
    # - always：永遠自動重啟
    # - no：不自動重啟
    restart: unless-stopped

    # =========================================================================
    # 連接埠設定
    # =========================================================================
    # 格式：「主機埠號:容器埠號」
    #
    # 範例：
    #   - "3000:3000"  → http://localhost:3000
    #   - "8080:3000"  → http://localhost:8080
    #   - "80:3000"    → http://localhost（需要 root 權限）
    #
    # 💡 若 3000 埠被佔用，改第一個數字即可
    ports:
      - "3000:3000"

    # =========================================================================
    # 資料儲存設定（⚠️ 非常重要）
    # =========================================================================
    # 格式：「主機路徑:容器路徑」
    #
    # ./data 是你主機上的實體資料夾（相對於 docker-compose.yml 的位置）
    # /app/data 是容器內的路徑
    #
    # 這裡存放：
    #   📁 上傳的檔案
    #   📁 轉換後的結果
    #   📁 使用者帳號資料（SQLite 資料庫）
    #
    # 🚨 重要提醒：
    #    1. 請務必先建立 data 資料夾再啟動容器！
    #       若資料夾不存在，Docker 可能會建立「匿名 volume」，
    #       這會導致容器刪除後資料全部遺失，且難以找回。
    #
    #    2. 如果你想用 Docker named volume 取代本地資料夾：
    #       - convertx_data:/app/data
    #       但資料會存在 Docker 內部，較難直接存取與備份。
    #
    #    3. 建議定期備份 data 資料夾！
    volumes:
      - ./data:/app/data

    # =========================================================================
    # 環境變數設定
    # =========================================================================
    environment:
      # -----------------------------------------------------------------------
      # 時區設定
      # -----------------------------------------------------------------------
      # 影響檔案時間戳記與日期顯示格式
      # 常用值：Asia/Taipei, Asia/Shanghai, America/New_York, Europe/London
      - TZ=Asia/Taipei

      # -----------------------------------------------------------------------
      # JWT 密鑰（🔐 強烈建議設定）
      # -----------------------------------------------------------------------
      # 用於使用者登入驗證的加密金鑰
      #
      # ⚠️ 若不設定會怎樣？
      #    系統會使用 randomUUID() 產生臨時金鑰，
      #    但每次容器重啟後金鑰會改變，導致：
      #    → 所有使用者的登入狀態失效
      #    → 所有人都需要重新登入
      #
      # ✅ 正確做法：
      #    設定一個長且隨機的字串（建議 32 字元以上）
      #    可以用 openssl rand -hex 32 產生
      #
      # 🚨 請務必將下面的值改成你自己的！
      - JWT_SECRET=請改成你自己的長隨機字串-至少32個字元-不要用這個預設值

      # -----------------------------------------------------------------------
      # 帳號註冊設定
      # -----------------------------------------------------------------------
      # true  = 允許任何人註冊新帳號
      # false = 關閉註冊功能
      #
      # 💡 注意：首次註冊的帳號不受此限制
      #    即使設為 false，仍可註冊第一個帳號（管理員）
      #
      # 📌 建議：
      #    - 首次部署時設為 true，註冊好帳號後改為 false
      #    - 或者直接設為 false，只用第一個註冊的帳號
      - ACCOUNT_REGISTRATION=true

      # -----------------------------------------------------------------------
      # HTTP 存取設定（🔒 安全性相關）
      # -----------------------------------------------------------------------
      # true  = 允許非 HTTPS 連線
      # false = 必須 HTTPS 連線（Cookie 設定 Secure 屬性）
      #
      # ⚠️ 這個設定影響登入功能是否正常運作！
      #
      # 📌 設定指南：
      #    🏠 本地測試（http://localhost）       → true
      #    🌐 遠端部署且有 HTTPS                → false
      #    🌐 遠端部署但沒有 HTTPS（不建議）    → true（但不安全）
      #
      # 🚨 常見問題：
      #    若設為 false 但實際用 HTTP 存取，
      #    會導致「登入後又被導回登入頁」的問題
      - HTTP_ALLOWED=true

      # -----------------------------------------------------------------------
      # Reverse Proxy 信任設定
      # -----------------------------------------------------------------------
      # 若你透過 Nginx / Traefik / Cloudflare / Caddy 等存取，設為 true
      #
      # 作用：讓應用程式信任 X-Forwarded-Proto 等 header，
      #       正確判斷連線是否為 HTTPS
      #
      # 📌 設定指南：
      #    直接存取容器（無 proxy）  → false
      #    透過 reverse proxy 存取  → true
      - TRUST_PROXY=false

      # -----------------------------------------------------------------------
      # 未登入存取設定
      # -----------------------------------------------------------------------
      # true  = 允許未登入的訪客使用轉換功能
      # false = 必須登入才能使用
      #
      # ⚠️ 設為 true 的風險：
      #    - 任何人都可以使用你的服務器資源
      #    - 可能被濫用（大量轉換、儲存空間耗盡）
      #
      # 📌 建議：除非你明確要提供公開服務，否則設為 false
      - ALLOW_UNAUTHENTICATED=false

      # -----------------------------------------------------------------------
      # 自動清理設定
      # -----------------------------------------------------------------------
      # 自動刪除超過 N 小時的轉換檔案
      # 設為 0 = 停用自動刪除
      #
      # 💡 建議設定適當的值，避免磁碟空間被轉換檔案塞滿
      - AUTO_DELETE_EVERY_N_HOURS=24

      # -----------------------------------------------------------------------
      # 進階設定（可選，需要時取消註解）
      # -----------------------------------------------------------------------
      # 子路徑部署（例如 https://example.com/convertx/）
      # - WEBROOT=/convertx

      # 隱藏歷史紀錄頁面
      # - HIDE_HISTORY=true

      # 日期格式語言（影響時間顯示格式）
      # - LANGUAGE=zh-TW

      # FFmpeg 硬體加速參數
      # - FFMPEG_ARGS=-hwaccel vaapi

      # 最大同時轉換數（0 = 無限制）
      # - MAX_CONVERT_PROCESS=4

  # ===========================================================================
  # ConvertX API Server（選用服務）
  # ===========================================================================
  #
  # 🆕 REST + GraphQL API 伺服器
  #
  # ⚠️ 這是選用服務，預設不啟動！
  #    使用 --profile api 才會啟動
  #
  # 🚀 啟動方式：
  #    docker compose --profile api up -d
  #
  # 📖 API 端點：
  #    - REST API:  http://localhost:3001/api/v1/
  #    - GraphQL:   http://localhost:3001/graphql
  #    - 健康檢查: http://localhost:3001/health
  #
  # 🔐 認證方式：
  #    所有 API（除健康檢查）都需要 JWT Bearer Token
  #    Token 需由外部認證服務產生
  #
  # ===========================================================================
  convertx-api:
    # 使用 profile 使其成為選用服務
    profiles:
      - api

    # 使用本地 Dockerfile 建置
    build:
      context: ./api-server
      dockerfile: Dockerfile

    # 或使用預建的 image（取消下面的註解）
    # image: convertx/convertx-api:latest

    container_name: convertx-api

    restart: unless-stopped

    # =========================================================================
    # 連接埠設定
    # =========================================================================
    # API Server 預設使用 3001 埠，避免與 Web UI (3000) 衝突
    ports:
      - "3001:3001"

    # =========================================================================
    # 資料儲存設定
    # =========================================================================
    # 與 Web UI 共用相同的 data 目錄
    # API Server 會在 data/uploads 和 data/output 下建立子目錄
    volumes:
      - ./data:/app/data

    # =========================================================================
    # 環境變數設定
    # =========================================================================
    # 可使用 env_file 載入 .env.api 檔案
    env_file:
      - path: .env.api
        required: false

    environment:
      # 時區設定
      - TZ=Asia/Taipei

      # -----------------------------------------------------------------------
      # API Server 專用設定
      # -----------------------------------------------------------------------
      # API 監聽地址與埠
      - API_HOST=0.0.0.0
      - API_PORT=3001

      # -----------------------------------------------------------------------
      # JWT 密鑰（🔐 必須設定）
      # -----------------------------------------------------------------------
      # ⚠️ 這是 API Server 驗證 Token 用的密鑰
      #    必須與產生 Token 的認證服務使用相同的密鑰
      #
      # 🚨 請務必修改為你自己的密鑰！
      - JWT_SECRET=${API_JWT_SECRET:-請設定你的API專用JWT密鑰}

      # -----------------------------------------------------------------------
      # 檔案儲存路徑
      # -----------------------------------------------------------------------
      - UPLOAD_DIR=/app/data/api-uploads
      - OUTPUT_DIR=/app/data/api-output

      # -----------------------------------------------------------------------
      # 其他設定
      # -----------------------------------------------------------------------
      # 最大檔案大小（預設 100MB）
      - MAX_FILE_SIZE=104857600

      # 日誌級別
      - RUST_LOG=convertx_api=info,tower_http=info

    # =========================================================================
    # 健康檢查
    # =========================================================================
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3001/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

    # =========================================================================
    # 資源限制（可選）
    # =========================================================================
    # deploy:
    #   resources:
    #     limits:
    #       memory: 2G
    #     reservations:
    #       memory: 512M