リリースパッケージとオフライン導入

このページで解決すること

Linux での主な導入経路はリリースパッケージです。配布物にはパッケージ、SHA-256 一覧、Sigstore 検証情報、イメージ一覧、アーキテクチャ別のオフラインイメージが含まれます。導入前に検証します。

設定のしかた

リリースのダウンロード案内スクリプト

1.14.0 以降、Linux ホストでは固定ファイル名の案内スクリプトを使えます。最新版のパッケージと SHA256SUMS を取得し、展開前にパッケージの SHA-256 を照合して /opt/custodexa に配置し、custodexa.sh のメニューを開きます。

set -o pipefail
curl -fsSL https://github.com/custodexa/custodexa/releases/latest/download/get-custodexa.sh | sudo bash

別の導入先を使う場合は --dir を付けます：

set -o pipefail
curl -fsSL https://github.com/custodexa/custodexa/releases/latest/download/get-custodexa.sh | sudo bash -s -- --dir /srv/custodexa

--version を付けなければ最新版を導入します。特定のバージョンを導入する場合は -- の後に --version <バージョン> を加えます。

先にスクリプトを確認する場合：

curl -fsSLO https://github.com/custodexa/custodexa/releases/latest/download/get-custodexa.sh
sudo bash get-custodexa.sh

Bash または Zsh で先に set -o pipefail を実行すると、案内スクリプトのダウンロードに失敗した場合にパイプライン全体がゼロ以外の終了コードを返します。ダウンロード後に実行する場合は、最初のコマンドが成功してから次を実行してください。CX_GET_RELEASE_BASE を別のリリース端点に設定すると、その端点のパッケージと SHA256SUMS の両方を信頼することになります。ハッシュの一致だけでは発行元の身元は確認できません。

案内スクリプトはパッケージ署名を検証しません。以下の手動手順で確認してください。イメージ署名は custodexa.sh が扱います。既存のデプロイは上書きせず、管理スクリプトに引き継ぎます。

手動ダウンロード、署名の検証、導入

次の 1 行目はリリースの MANIFEST.json から最新バージョンを読み取ります。別のバージョンを使う場合は VERSION=X.Y.Z のように自分で設定してください。続いてパッケージ、SHA256SUMS、SHA256SUMS.sigstore.json を取得し、同じディレクトリで検証して導入します。

VERSION=$(curl -fsSL https://github.com/custodexa/custodexa/releases/latest/download/MANIFEST.json | sed -n 's/.*"version": *"\([0-9][0-9.]*\)".*/\1/p')
base=https://github.com/custodexa/custodexa/releases/download/v${VERSION}
curl -fsSL -O "$base/custodexa-${VERSION}.tar.gz" -O "$base/SHA256SUMS" -O "$base/SHA256SUMS.sigstore.json"
sha256sum --ignore-missing -c SHA256SUMS
cosign verify-blob --bundle SHA256SUMS.sigstore.json \
  --certificate-identity "https://github.com/custodexa/custodexa/.github/workflows/release-images.yml@refs/tags/v${VERSION}" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  SHA256SUMS
sudo tar -xzf "custodexa-${VERSION}.tar.gz" -C /opt
sudo /opt/custodexa/custodexa.sh install

導入処理はホストと Docker を確認し、.env を作成し、イメージを取得して検証し、サービスを起動してヘルスチェックを待ちます。イメージはローカル、オフラインパッケージ、GHCR、Docker Hub、ソースビルドの順に探します。永続データは DATA_PATH に置きます。初期パスワードは初回ログイン後に画面で変更します。

導入には custodexa.sh を使います。install とメニューでは「自動」または「パッケージ内のソースからビルド」を選べます。コマンドの --images-from auto|source は省略時に auto です。自動ではホスト上のイメージ、オフラインバンドル、GHCR、Docker Hub、最後にローカルビルドの順に探します。source はパッケージ内のソースを検証して backend と frontend をビルドします。上流イメージ、ベースイメージ、ビルド依存関係は別途取得するため、完全なオフライン手段ではありません。--images <バンドル> は auto とだけ併用できます。取得や検証などの長い処理は開始前に [ .. ]、完了時に [ OK ]、[WARN] または [FAIL] を表示します。

sudo /opt/custodexa/custodexa.sh install --images-from source

オフラインイメージ

ホストに合う custodexa-images-<バージョン>-amd64.tar または aarch64 版を取得し、同じ版の SHA256SUMS をイメージと同じディレクトリに置きます。前に設定した VERSION を使い、両方を /srv/custodexa-<バージョン>/ に置いた例では、導入前に読み込みます。

sudo /opt/custodexa/custodexa.sh load "/srv/custodexa-${VERSION}/custodexa-images-${VERSION}-amd64.tar"
sudo /opt/custodexa/custodexa.sh install

引数なしの sudo /opt/custodexa/custodexa.sh はメニューを開きます。未導入のときは導入、バックアップからの復元、イメージの読み込みを、導入後は状態、起動、停止、アップグレード、バックアップ、復元、イメージの読み込み、ヘルプを選べます。更新前の版に戻すには rollback サブコマンドを使います。アップグレードとロールバックを参照してください。--help はコマンド一覧、--lang zh-TW、--lang en、--lang ja はメニュー言語の指定です。sudo /opt/custodexa/custodexa.sh status でサービスとバージョンを確認します。

監査で見えること

導入後のログインと管理下のセッションは監査記録に入ります。コマンド記録は検索用で、テキストセッションの事実の出どころは録画です。エコーされない入力はコマンド本文の記録に残りません。クエリコンソールの構造化された文の記録は、そのクエリの事実の出どころです。