用 Docker Compose 部署

一台機器就能執行完整的爬山虎：PostgreSQL、伺服器和 BostonIvy Web，編排寫在 bostonivy-os 儲存庫的 deploy/compose.yaml 裡。這是最快的入門方式，家庭或小團隊用它就夠了。

開始之前

Docker 和 Compose v2（docker compose version 顯示 v2.x）。
部署檔案：bostonivy-os 的 deploy 資料夾，裡面有 compose.yaml、https.yaml 和 .env.example。
映像檔的讀取權限。 映像檔是 GitHub Container Registry 上的私有套件。用具有 read:packages 權限的 GitHub 權杖登入一次：

echo "$GITHUB_TOKEN" | docker login ghcr.io -u <你的 GitHub 使用者名稱> --password-stdin

啟動爬山虎

從範例建立設定：
```
cd deploy
cp .env.example .env
```
產生伺服器金鑰，填進 .env 的 BOSTONIVY_AUTH_SECRET：
```
docker compose run --rm --no-deps bostonivy keygen
```
啟動所有服務：
```
docker compose up -d
```
開啟 http://localhost:8080 註冊帳號。新資料庫上第一個註冊的帳號會自動成為管理員；之後是否允許其他人註冊，由 auth.open_registration 和管理面板裡的設定決定。

docker compose ps 應該顯示三個服務都是 healthy。伺服器每次啟動都會自動遷移資料庫，不需要再執行其他指令。

範例 .env 裡 BOSTONIVY_COOKIE_SECURE=false，只適合在 http://localhost 上試用。給其他人使用之前，請先設定好 HTTPS（見下文），並把它改成 true。

設定

所有設定都在 deploy/.env 裡：

變數	說明
`BOSTONIVY_AUTH_SECRET`	必填。所有簽章和加密金鑰都由它衍生。遺失後所有人都要重新登入，加密儲存的 TOTP 和 webhook 密鑰也無法解開。請妥善備份
`BOSTONIVY_URL`	使用者連線的網址，郵件裡的連結和分享連結都用它
`BOSTONIVY_PORT`	本機開放的連接埠，預設 `8080`
`BOSTONIVY_COOKIE_SECURE`	正式環境設為 `true`，這需要 HTTPS。只有在 `http://localhost` 上試用時設為 `false`，否則重新整理頁面後會被登出
`BOSTONIVY_SMTP_URL`、`BOSTONIVY_MAIL_FROM`	寄信設定，例如 `smtps://user:password@smtp.example.com` 和 `BostonIvy <noreply@example.com>`。留空表示不寄信；`log` 表示把郵件寫進伺服器記錄，適合試用
`POSTGRES_PASSWORD`	資料庫密碼
`BOSTONIVY_VERSION`	映像檔標籤；`latest` 跟隨最新版本
`BOSTONIVY_SITE`	Caddy 的網站位址，見下文的 HTTPS 一節

其他伺服器設定（流量限制、Redis、webhook、物件儲存、刪除帳號的寬限期等）都可以用 BOSTONIVY_<區段>__<鍵> 形式的環境變數設定，例如 BOSTONIVY_STORAGE__KIND=s3，加在 compose.yaml 的 bostonivy.environment 裡即可。完整的設定項目見 bostonivy-os 裡的 bostonivy.example.toml。

HTTPS

二選一：

讓 Caddy 申請憑證。 把網域指向這台機器，然後在 .env 裡設定：
```
BOSTONIVY_SITE=tasks.example.com
BOSTONIVY_URL=https://tasks.example.com
BOSTONIVY_COOKIE_SECURE=true
```
再加上 HTTPS 的覆寫檔啟動，它會開放 80 和 443 連接埠：
```
docker compose -f compose.yaml -f https.yaml up -d
```
Caddy 會自動申請和續期憑證，憑證存在 caddy 磁碟區裡。
放在既有的反向代理後面。 保持 BOSTONIVY_SITE=:80，把代理指向 BOSTONIVY_PORT，並確認它會轉送 /api/v1/realtime 上的 WebSocket 連線，即時更新靠它推送。

備份與升級

需要備份三樣東西：

資料庫：

docker compose exec postgres pg_dump -U bostonivy bostonivy > backup.sql

附件和頭像： files 磁碟區（如果已改用 S3，就在儲存桶裡）。
金鑰： .env 裡的 BOSTONIVY_AUTH_SECRET。

升級時拉取新映像檔並重新啟動：

docker compose pull && docker compose up -d

新版本啟動時會自動遷移資料庫。遷移只增不刪，搭配備份可以退回上一個版本。

命令列

docker compose exec bostonivy bostonivy admin promote <使用者名稱>   # 設為管理員
echo "新密碼" | docker compose exec -T bostonivy bostonivy admin set-password <使用者名稱>
docker compose exec bostonivy bostonivy health                      # 健康檢查

自行建置映像檔

把 bostonivy-web 簽出到 bostonivy-os 旁邊，或者在 .env 裡用 BOSTONIVY_WEB_SOURCE 指定路徑。網頁版依賴私有的爬山虎設計套件，所以建置時需要一個能讀取 IvyLabsApp 私有儲存庫的權杖。權杖只作為建置密鑰使用，不會寫進映像檔：

cd deploy
GITHUB_TOKEN=$(gh auth token) docker compose build
docker compose up -d