# ==============================================================================
# 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 為你自己的隨機字串
# ==============================================================================

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