Helm で Kubernetes にデプロイする

BostonIvy の Helm chart には、サーバー（API、MCP、CalDAV、バックグラウンドジョブ）、同じアドレスで配信する BostonIvy Web、そして手早く始めるための同梱 PostgreSQL が含まれます。サーバーのリリースごとに新しい chart が oci://ghcr.io/ivylabsapp/charts/bostonivy に公開されます。

始める前に

Kubernetes クラスター、kubectl、そして OCI レジストリから chart をインストールできる Helm 3.8 以降。
Ingress コントローラー（例では ingress-nginx）と、それを指すドメイン名。なくても試すことはできます。Ingress なしで試すを参照してください。
read:packages スコープを持つ GitHub トークン。イメージと chart は GitHub Container Registry の非公開パッケージです。

インストール

名前空間と、非公開イメージを取得するための pull シークレットを作ります。

kubectl create namespace bostonivy
kubectl -n bostonivy create secret docker-registry ghcr \
  --docker-server=ghcr.io --docker-username=<GitHub のユーザー名> --docker-password=<read:packages を持つトークン>

chart を取得できるように、Helm をレジストリにサインインさせます。

echo "$GITHUB_TOKEN" | helm registry login ghcr.io -u <GitHub のユーザー名> --password-stdin

設定をファイル（たとえば values.yaml）に書きます。url は必須で、メール内のリンク、共有リンク、OAuth と OIDC のコールバックに使われます。

url: https://tasks.example.com
imagePullSecrets:
  - name: ghcr
ingress:
  enabled: true
  className: nginx
  annotations:
    # リアルタイム更新は /api/v1/realtime の長時間 WebSocket。アップロードは最大 64 MiB
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-body-size: 64m
  tls:
    - secretName: bostonivy-tls
      hosts: [tasks.example.com]

bostonivy-tls はドメインの証明書です。自分で作る TLS Secret か、cert-manager が作るものを使います。

インストールします。
```
helm install ivy oci://ghcr.io/ivylabsapp/charts/bostonivy --version 0.7.0 -n bostonivy -f values.yaml
```
このページの例ではリリース名を ivy としているので、リソース名は ivy-bostonivy-… になります。bostonivy-os をチェックアウトしていれば、deploy/helm/bostonivy からもインストールできます。

最初の管理者を作る

インストール後に Helm も同じ手順を表示します。パスワードは表示されずに読み取られます。

printf 'Password: '; read -rs PW; echo
printf '%s\n' "$PW" | kubectl -n bostonivy exec -i deploy/ivy-bostonivy-server -- bostonivy admin create-user <ユーザー名> <メールアドレス> --admin
unset PW

サーバーのシークレットをバックアップする

サーバーのシークレットと同梱データベースのパスワードはインストール時に生成され、アップグレードのたびに保持されます。保存先は Secret ivy-bostonivy-secrets で、アンインストールしても Helm は削除しません。署名と暗号化の鍵はすべてサーバーのシークレットから導出されます。失うと全員がサインインし直すことになり、保存済みの TOTP や webhook のシークレットも読めなくなります。今のうちに安全な場所へコピーしてください。

kubectl -n bostonivy get secret ivy-bostonivy-secrets -o jsonpath='{.data.auth-secret}' | base64 -d

自分のシークレットを使う場合は auth.secret を設定するか、自分で管理する Secret の auth-secret キーに入れて auth.existingSecret を設定します。

Ingress なしで試す

ingress.enabled はオフのまま auth.cookieSecure=false を設定し、Web サービスを手元のマシンに転送します。

kubectl -n bostonivy port-forward svc/ivy-bostonivy-web 8080:80

そして http://localhost:8080 を開きます。HTTPS で配信するようになったら、auth.cookieSecure を true に戻してください。

設定値

値	既定	役割
`url`	必須	利用者が BostonIvy にアクセスするアドレス。リンク、OAuth、OIDC のコールバックに使われます
`imagePullSecrets`	`[]`	非公開イメージを取得するための pull シークレット
`auth.secret`、`auth.existingSecret`	自動生成	サーバーのシークレット。直接指定するか、自分の Secret（キー `auth-secret`）から取ります
`auth.cookieSecure`	`true`	HTTPS の背後ではオンのまま。オフは素の http で試すときだけ
`database.url`、`database.existingSecret`	同梱	外部の PostgreSQL 16 以降。空なら同梱のものを使います
`postgresql.enabled`	`true`	クラスター内の PostgreSQL 1 台。お試しや小規模向け
`mail.smtpUrl`、`mail.from`	空	例：`smtp://user:password@host:587`、または `log`。空ならメールを送りません
`config`	空	TOML で書く追加のサーバー設定。`[[auth.oidc]]` のサインインプロバイダーなど
`server.env`、`server.envFrom`	`[]`	そのほかの `BOSTONIVY_<セクション>__<キー>` 設定
`server.replicas`	`1`	2 以上にするには S3 ストレージと `worker.separate` が必要
`worker.separate`、`worker.replicas`	`false`、`1`	バックグラウンドジョブ（メール、webhook、リマインダー、メンテナンス）を専用の Pod で動かします
`persistence.*`	10Gi、ReadWriteOnce	ストレージがローカルのときの添付ファイルとアバター
`web.image.tag`	`0.2.0`	配信する BostonIvy Web のリリース
`ingress.*`	オフ	ホストは既定で `url` のもの。リアルタイム更新のため、長時間の WebSocket 読み取りを許可してください

データベース

同梱の PostgreSQL は Pod 1 つだけで、お試しや小規模な構成向けです。本番ではマネージドデータベースかオペレーターを使い、BostonIvy の接続先をそちらにします。

postgresql:
  enabled: false
database:
  url: postgres://bostonivy:<パスワード>@db.example.com:5432/bostonivy

接続先を自分の Secret に入れて database.existingSecret を設定することもできます。BostonIvy には PostgreSQL 16 以降が必要です。

メール、サインイン、そのほかの設定

メール： mail.smtpUrl と mail.from。log にするとメールをサーバーログに書き出すので、お試しに便利です。
TOML のサーバー設定： config には TOML を書けます。たとえばサインインプロバイダー：
```
config: |
  [[auth.oidc]]
  id = "google"
  # ほかの項目は bostonivy.example.toml を参照
```
そのほか： server.env に BOSTONIVY_<セクション>__<キー> 形式の変数を渡せます。すべての設定は bostonivy-os の bostonivy.example.toml にあります。

スケールアウト

ローカルに保存するファイルを除けば、サーバー自体は状態を持ちません。複数のレプリカで動かすには：

server:
  replicas: 3
  env:
    - name: BOSTONIVY_STORAGE__KIND
      value: s3
    # さらに bostonivy.example.toml の [storage] にあるバケットの設定
worker:
  separate: true
persistence:
  enabled: false

ファイルは、1 つの Pod にしかマウントできないボリュームではなく、S3 互換ストレージに保存します。
worker.separate はバックグラウンドジョブを専用の Pod に移すので、ジョブはサーバーのレプリカごとではなく一度だけ実行されます。
レプリカ間でレート制限のカウンターを共有したい場合は、server.env に BOSTONIVY_REDIS__URL を設定します。
リアルタイム更新、セッションの失効、プラグインは PostgreSQL を通じてレプリカ間で同期されるので、ほかに必要なものはありません。

アップグレードとバックアップ

新しいリリースの chart でアップグレードします。

helm upgrade ivy oci://ghcr.io/ivylabsapp/charts/bostonivy --version <新しいバージョン> -n bostonivy -f values.yaml

サーバーの Pod が順に入れ替わり、新しいバージョンが起動時にデータベースをマイグレーションします。マイグレーションは追加だけで削除はしないので、バックアップと組み合わせれば元に戻せます。

バックアップするものは 3 つです。

データベース。 同梱の PostgreSQL の場合：

kubectl -n bostonivy exec ivy-bostonivy-postgresql-0 -- pg_dump -U bostonivy bostonivy > backup.sql

添付ファイルとアバター： ファイル用のボリューム、またはバケット。
サーバーのシークレット： auth-secret（サーバーのシークレットをバックアップするを参照）。