KB: セルフアップデートプロセス

triggerfish update の仕組み、発生する可能性のある問題、およびその回復方法。

仕組み

updateコマンドはGitHubから最新リリースをダウンロードしてインストールします：

1. バージョン確認。 GitHub APIから最新リリースタグを取得します。すでに最新バージョンを使用している場合は早期終了します：

   Already up to date (v0.4.2)

   開発ビルド（VERSION=dev）はバージョン確認をスキップし、常に続行します。

2. プラットフォーム検出。 OSとアーキテクチャ（linux-x64、linux-arm64、macos-x64、macos-arm64、windows-x64）に基づいて正しいバイナリアセット名を決定します。

3. ダウンロード。 GitHubリリースからバイナリと SHA256SUMS.txt を取得します。

4. チェックサム検証。 ダウンロードされたバイナリのSHA256を計算し、SHA256SUMS.txt のエントリと比較します。チェックサムが一致しない場合は更新が中止されます。

5. デーモンの停止。 バイナリを置き換える前に実行中のデーモンを停止します。

6. バイナリの置き換え。 プラットフォーム固有：

   • Linux/macOS: 旧バイナリをリネームし、新しいものを所定の場所に移動
   • macOS 追加ステップ: xattr -cr で検疫属性を除去
   • Windows: 旧バイナリを .old にリネーム（Windowsは実行中の実行ファイルを上書きできない）、その後新しいバイナリを元のパスにコピー

7. デーモンの再起動。 新しいバイナリでデーモンを起動します。

8. 変更履歴。 新バージョンのリリースノートを取得して表示します。

Sudoによる昇格

バイナリがrootアクセスを必要とするディレクトリ（例：/usr/local/bin）にインストールされている場合、アップデーターは sudo を使用して昇格するためのパスワードを要求します。

クロスファイルシステムの移動

ダウンロードディレクトリとインストールディレクトリが異なるファイルシステムにある場合（/tmp が別パーティションにある場合に一般的）、アトミックリネームが失敗します。アップデーターはコピー後に削除にフォールバックしますが、これは安全ですが短時間両方のバイナリがディスクに存在します。

発生する可能性のある問題

「チェックサム検証の例外」

ダウンロードされたバイナリが期待されるハッシュと一致しません。通常の原因：

• ダウンロードが破損した（ネットワーク問題）
• リリースアセットが古いか部分的にアップロードされている

修正方法: 数分待ってから再試行します。問題が解決しない場合は、リリースページからバイナリを手動でダウンロードしてください。

「SHA256SUMS.txt にアセットが見つからない」

リリースがお使いのプラットフォームのチェックサムなしで公開されました。これはリリースパイプラインの問題です。

修正方法: GitHub issueを提出してください。

「バイナリの置き換えに失敗」

アップデーターが旧バイナリを新しいものに置き換えられませんでした。一般的な原因：

• ファイル権限（バイナリがrootに所有されているが通常ユーザーで実行している）
• ファイルがロックされている（Windows：別のプロセスがバイナリを開いている）
• 読み取り専用ファイルシステム

修正方法：

1. デーモンを手動で停止します：triggerfish stop
2. 古くなったプロセスを終了します
3. 適切な権限で更新を再試行します

「チェックサムファイルのダウンロードに失敗」

GitHubリリースから SHA256SUMS.txt をダウンロードできません。ネットワーク接続を確認して再試行してください。

Windows の .old ファイルのクリーンアップ

Windowsの更新後、旧バイナリは triggerfish.exe.old にリネームされます。このファイルは次回起動時に自動的にクリーンアップされます。クリーンアップされない場合（例：新しいバイナリが起動時にクラッシュする）、手動で削除できます。

バージョン比較

アップデーターはセマンティックバージョニング比較を使用します：

• 先頭の v プレフィックスを削除します（v0.4.2 と 0.4.2 はどちらも受け付けられます）
• major、minor、patchを数値で比較します
• プレリリースバージョンを処理します（例：v0.4.2-rc.1）

手動更新

自動アップデーターが動作しない場合：

1. GitHub Releasesからお使いのプラットフォーム向けバイナリをダウンロードします
2. デーモンを停止します：triggerfish stop
3. バイナリを置き換えます：

   # Linux/macOS
   sudo cp triggerfish-linux-x64 /usr/local/bin/triggerfish
   sudo chmod +x /usr/local/bin/triggerfish
   
   # macOS: 検疫を除去
   xattr -cr /usr/local/bin/triggerfish

4. デーモンを起動します：triggerfish start

Docker更新

Dockerデプロイメントはバイナリアップデーターを使用しません。コンテナイメージを更新します：

# ラッパースクリプトを使用
triggerfish update

# 手動で
docker compose pull
docker compose up -d

ラッパースクリプトは最新イメージをプルし、コンテナが実行中の場合は再起動します。

変更履歴

更新後、リリースノートは自動的に表示されます。手動で表示することもできます：

triggerfish changelog              # 現在のバージョン
triggerfish changelog --latest 5   # 直近5つのリリース

更新後に変更履歴の取得が失敗した場合、ログに記録されますが更新自体には影響しません。