# 管理ツールによる一括セットアップ {#admin-deployment} 管理ツールを使って組織内の開発者端末に一括でセットアップするために利用できる、配信用スクリプトを提供しています。ご利用の管理ツールに応じて、カスタマイズしてご利用ください。 :::info 有料機能 この機能を利用するには、Guard を有効化した Takumi サブスクリプションが必要です。詳しくは[料金と請求](/docs/ja/t/guard/billing/index.md)を参照してください。 ::: ## 概要 {#overview} 一括セットアップは、管理者が管理ツール（Jamf、Intune、Ansible など）を使って、組織内の開発者端末に Takumi Guard のレジストリプロキシ設定を一括で配信する仕組みです。開発者自身がコマンドを実行したり、設定ファイルを編集する必要はありません。 以下の図は、一括セットアップの全体構成を示しています。 ```mermaid flowchart LR subgraph AdminSide[管理者 / 管理ツール MDM等] Admin[管理者] MDM[配信ツール] end subgraph Cloud[Takumi / Shisho Cloud 管理画面] Console[コンソール] API[Guard API] end Dev1[開発者端末 A] Dev2[開発者端末 B]:::faded Dev3[開発者端末 ...]:::faded Proxy[Guard レジストリプロキシ] Admin -- Bot 作成と管理用 API キー取得 --> Console Admin -- スクリプト登録（管理用APIキー含） --> MDM MDM -- セットアップスクリプト実行 --> Dev1 MDM -.-> Dev2 MDM -.-> Dev3 Dev1 & Dev2 & Dev3 -- レジストリ用の個別トークン発行 --> API Dev1 & Dev2 & Dev3 -- パッケージ取得 --> Proxy classDef faded opacity:0.4 ``` 管理者がコンソールで Bot と管理用 API キーを作成し、セットアップスクリプトとともに管理ツール経由で各端末に配信します。各端末ではスクリプトが自動的に Guard API にトークン発行をリクエストし、npm・pip・uv・Poetry の設定ファイルを更新します。以降、各端末からのパッケージインストールは Guard レジストリプロキシを経由するようになります。 セットアップスクリプトによって発行されたトークンは、コンソールの **Guard** > **トークン** で一覧・管理できます。 ![トークン管理画面](/docs/ja/_md-assets/345d7d2982-ui-tokens.png) セットアップは大きく 2 つのフェーズに分かれます。 1. **準備**：Takumi / Shisho Cloud コンソールで Bot を作成し、セットアップスクリプトをダウンロードします 2. **配信**：管理ツール用のラッパースクリプトを作成し、セットアップスクリプトと合わせて対象端末に配信します ## 前提条件 {#prerequisites} 配信の前に、Takumi / Shisho Cloud コンソールで以下の設定を完了してください。 1. **Bot を作成する**：設定 > Bot ページの「ボットの追加」ボタンから作成してください ![設定 > Bot ページの「ボットの追加」ボタン](/docs/ja/_md-assets/c2c6b44476-takumi-guard-1.png) 2. **ロールを付与する**：Bot に「Takumi Guard トークン発行者」ロールを付与してください ![ボットの追加画面で「Takumi Guard トークン発行者」ロールを選択](/docs/ja/_md-assets/277b035a4c-takumi-guard-2.png) 3. **API キーを取得する**：作成した Bot の詳細ページで「API キーの作成」ボタンから静的 API キーを作成し、安全に保管してください ![Bot 詳細ページの「API キーの作成」ボタン](/docs/ja/_md-assets/6a42c26f25-takumi-guard-3.png) :::info Bot の作成と API キーの発行手順の詳細は[こちら](/docs/ja/c/accessing-via-shishoctl-cli/index.md#sign-in-with-an-api-key)も参照してください。 ::: ## セットアップスクリプト {#setup-script} トークンの発行とパッケージマネージャーの設定を行うセットアップスクリプトを提供しています。お使いのプラットフォームに合わせてダウンロードしてください。 - **macOS / Linux:** [https://shisho.dev/releases/takumi-guard-setup-0.1.1.sh](https://shisho.dev/releases/takumi-guard-setup-0.1.1.sh) - **Windows:** [https://shisho.dev/releases/takumi-guard-setup-0.1.1.ps1](https://shisho.dev/releases/takumi-guard-setup-0.1.1.ps1) :::info 対象端末には `curl` がインストールされている必要があります（macOS および Linux の場合）。 ::: ### 使い方 {#usage} セットアップスクリプトは、**実行したユーザーの設定ファイルのみ**を変更します。組織内の全ユーザーに一括展開する場合は、後述の[配信例](#deployment-examples)のラッパースクリプトを使用してください。 セットアップスクリプトを以下のように実行してください。API キーは環境変数 `TG_BOT_API_KEY` で渡してください。 ```sh TG_BOT_API_KEY="shisho_apikey_..." ./setup.sh ``` 各パラメータの意味は以下の通りです。 | パラメータ | 説明 | | ----------------- | ----------------------------------------- | | `TG_BOT_API_KEY` | Bot の API キー（環境変数） | | `BOT_ID` | Takumi / Shisho Cloud コンソールの Bot ID | | `USER_IDENTIFIER` | デバイスやユーザーを識別するユニークな値 | 対象を限定したい場合は、第 3 引数でスコープを指定してください。 ```sh TG_BOT_API_KEY="..." ./setup.sh BOT_ID USER_IDENTIFIER npm,pypi ``` | スコープ | 設定されるパッケージマネージャー | | -------- | -------------------------------- | | `npm` | npm, pnpm, yarn（v2+）, bun | | `pypi` | pip, uv, poetry | ## 参考：USER_IDENTIFIER の決め方 {#user-identifier} `USER_IDENTIFIER` は、デバイスやユーザーを識別する文字列です。組織内で一貫した命名規則を決めておくことを推奨します。 **文字種の制約は以下の通りです。** - 使用可能な文字: `a-z`, `A-Z`, `0-9`, `-`, `_`, `.` - 文字数: 4〜255 文字 以下の例を参考に、組織に合った識別子を選んでください。 | 例 | 値 | 説明 | | ------------------------------------------ | -------------------- | -------------------------------------------------- | | デバイスのシリアルナンバー + OS ユーザー名 | `C02X1234_jdoe` | デバイス BIOS のハードウェアシリアルナンバーを使用 | | 資産管理 ID + 社員 ID | `ASSET0042_EMP12345` | 組織で管理している ID を使用 | | MDM のデバイス ID + OS ユーザー名 | `a401c7d0_jdoe` | MDM ツールが割り当てるデバイス ID を使用 | :::warning 選択した識別子が組織内でユニークであることを確認してください。一部の識別子（シリアルナンバーなど）は、自作 PC や仮想マシンなどの環境では空になったり、デバイス間でユニークでない場合があります。各デバイスとユーザーを確実に区別できる値を使用してください。 ::: ## 参考：詳細な挙動 {#behavior} ### 初回実行時 {#first-run} セットアップスクリプトがトークンを発行し、既存の設定ファイルのタイムスタンプ付きバックアップ（例：`~/.npmrc-backup-20260408-162351`）を作成してから、Guard の設定を追記します。既存の Guard 以外の設定は変更されません。 ### 再実行時 {#re-run} 既存のトークンを検出して再利用するため、新しいトークンは発行されません。既に Guard が設定済みのツールはスキップされます（変更もバックアップも行われません）。スコープの増分追加にも対応しています。たとえば、先に `npm` スコープで実行し、後から `pypi` スコープを追加できます。 ### 手動ロールバック {#manual-rollback} セットアップスクリプトは、設定ファイルを変更する前にタイムスタンプ付きの永続バックアップを作成します（例：`~/.npmrc-backup-20260408-162351`）。Guard の設定を元に戻したい場合は、このバックアップファイルを元のファイル名にコピーしてください（例：`cp ~/.npmrc-backup-20260408-162351 ~/.npmrc`）。 :::note トークンは初回実行時にのみ発行されます。再実行時は既存のトークンが再利用されます。端末の入れ替えや従業員の退職などで不要になったトークンは、Takumi / Shisho Cloud コンソールから失効させてください。 ::: :::warning パッケージマネージャーに別のレジストリ（プライベート npm レジストリなど）が既に設定されている場合、セットアップスクリプトは既存のレジストリ設定を Guard のレジストリで上書きします。上書き前にタイムスタンプ付きのバックアップファイルが作成されますが、念のため、配信前に対象端末で使用中のレジストリ設定を確認してください。 ::: ## 配信例 {#deployment-examples} セットアップスクリプトの配信方法は、お使いの管理ツールや OS によって異なります。ここでは、代表的な配信パターンを紹介します。 ### macOS / Linux {#wrapper-macos-linux} 管理ツールによるスクリプト実行は通常 root 権限で行われます。各開発者の環境に展開するには、以下のようなラッパースクリプトでユーザーを切り替えて実行してください。 :::note root ユーザーにも Guard を適用したい場合は、ラッパースクリプト内でユーザー切り替えなしにセットアップスクリプトを一度実行してください。 ::: #### macOS {#wrapper-macos} ```sh #!/bin/bash # deploy-guard.sh：Admin deployment wrapper # TODO: Replace with your Bot ID and API key from Shisho Cloud console BOT_ID="BTXXXXXXXXXXXXXXXXXXXXXXXXXX" export TG_BOT_API_KEY="shisho_apikey_XXXXX" # Download the setup script # Replace {VERSION} with the actual version number curl -sL -o /tmp/takumi-guard-setup.sh https://shisho.dev/releases/takumi-guard-setup-{VERSION}.sh chmod 755 /tmp/takumi-guard-setup.sh # Get the device serial number for USER_IDENTIFIER generation SERIAL=$(ioreg -l | grep IOPlatformSerialNumber | awk -F'"' '{print $4}') # Run the setup script for each user on this machine for USER_HOME in /Users/*; do USER_NAME=$(basename "$USER_HOME") # Skip system directories and non-existent paths [ "$USER_NAME" = "Shared" ] && continue [ ! -d "$USER_HOME" ] && continue # Skip if the user account does not exist id "$USER_NAME" >/dev/null 2>&1 || continue # Build a unique identifier for this device + user combination USER_IDENTIFIER="${SERIAL}_${USER_NAME}" # Run the setup script as this user (login shell for PATH resolution) sudo -u "$USER_NAME" -i -H env TG_BOT_API_KEY="$TG_BOT_API_KEY" \ /tmp/takumi-guard-setup.sh "$BOT_ID" "$USER_IDENTIFIER" echo "[Done] $USER_NAME (USER_IDENTIFIER: $USER_IDENTIFIER)" done # Clean up credentials and temporary files unset TG_BOT_API_KEY rm -f /tmp/takumi-guard-setup.sh ``` #### Linux {#wrapper-linux} ```bash #!/bin/bash # deploy-guard.sh：Admin deployment wrapper # TODO: Replace with your Bot ID and API key from Shisho Cloud console BOT_ID="BTXXXXXXXXXXXXXXXXXXXXXXXXXX" export TG_BOT_API_KEY="shisho_apikey_XXXXX" # Download the setup script # Replace {VERSION} with the actual version number curl -sL -o /tmp/takumi-guard-setup.sh https://shisho.dev/releases/takumi-guard-setup-{VERSION}.sh chmod 755 /tmp/takumi-guard-setup.sh # Get the device serial number for USER_IDENTIFIER generation SERIAL=$(dmidecode -s system-serial-number) # Run the setup script for each user on this machine for USER_HOME in /home/*; do USER_NAME=$(basename "$USER_HOME") # Skip non-existent paths [ ! -d "$USER_HOME" ] && continue # Skip if the user account does not exist id "$USER_NAME" >/dev/null 2>&1 || continue # Build a unique identifier for this device + user combination USER_IDENTIFIER="${SERIAL}_${USER_NAME}" # Run the setup script as this user (login shell for PATH resolution) sudo -u "$USER_NAME" -i -H env TG_BOT_API_KEY="$TG_BOT_API_KEY" \ /tmp/takumi-guard-setup.sh "$BOT_ID" "$USER_IDENTIFIER" echo "[Done] $USER_NAME (USER_IDENTIFIER: $USER_IDENTIFIER)" done # Clean up credentials and temporary files unset TG_BOT_API_KEY rm -f /tmp/takumi-guard-setup.sh ``` ### Windows {#deployment-windows} 管理ツールで、スクリプトを配布し、ログインユーザーの権限でセットアップスクリプトを直接実行してください。 ## セキュリティ上の注意事項 {#security} - **API キーの取り扱い**：Bot の API キーが漏洩した場合は、Takumi / Shisho Cloud コンソールから直ちに無効化してください。既に発行済みのトークンには影響しません。 - **キーのローテーション**：すべての対象端末への配信が完了したら、予防策として Takumi / Shisho Cloud コンソールで Bot の API キーをローテーションしてください。 - **トークンの失効**：トークンが漏洩した場合は、Takumi / Shisho Cloud コンソールからトークンを失効させてください。失効は最大 60 秒で反映されます。