> ## Documentation Index
> Fetch the complete documentation index at: https://novita.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ビルドと運用

## ビルド

テンプレート定義の準備ができたら、`Template.build(...)` を使用してビルドします。ビルドでは、テンプレート名に加えて、CPU、メモリ、タグ、キャッシュ動作、ビルドログのコールバックなどの任意のビルド設定を受け付けます。

<CodeGroup>
  ```ts JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox, Template } from "novita-sandbox"

  const template = Template().fromImage("python:3.12")

  const build = await Template.build(template, "my-python-template", {
    cpuCount: 2,
    memoryMB: 1024,
  })

  const sandbox = await Sandbox.create(build.templateId)
  console.log(sandbox.sandboxId)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.core import Sandbox, Template

  template = Template().from_image("python:3.12")

  build = Template.build(
      template,
      "my-python-template",
      cpu_count=2,
      memory_mb=1024,
  )

  sandbox = Sandbox.create(build.template_id)
  print(sandbox.sandbox_id)

  sandbox.kill()
  ```
</CodeGroup>

プロセス全体の完了を待たずにビルドを作成したい場合は、`Template.buildInBackground(...)` / `Template.build_in_background(...)` を使用し、後でビルドステータスを確認します。

## 名前

すべてのビルドにはテンプレート名が必要です。論理的なテンプレートファミリーでは、名前を安定させてください。例:

* `my-python-template`
* `agent-runtime-base`
* `sandbox-webapp`

名前は、テンプレートファミリーの長期的な識別子として扱います。返されるテンプレート ID は、実行時に使用する不変のビルド出力です。

## タグとバージョン管理

タグを使用すると、基になるテンプレート名を変更せずに、リリース管理用にビルドにラベルを付けることができます。

一般的なパターンには次のようなものがあります。

* `v1.0.0` などのセマンティックバージョン
* `staging` や `production` などの昇格ラベル
* `latest` などの移動チャネル

タグはビルド中に割り当てることも、ビルド後にテンプレートタグ API を使用して割り当てることもできます。

<CodeGroup>
  ```ts JavaScript & TypeScript icon="js" theme={"system"}
  import { Template } from "novita-sandbox"

  const template = Template().fromPythonImage("3.12")

  const build = await Template.build(template, "agent-runtime-base", {
    tags: ["v1.0.0", "latest"],
  })

  await Template.assignTags("agent-runtime-base:v1.0.0", "production")

  const tags = await Template.getTags(build.templateId)
  console.log(tags)
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.core import Template

  template = Template().from_python_image("3.12")

  build = Template.build(
      template,
      "agent-runtime-base",
      tags=["v1.0.0", "latest"],
  )

  Template.assign_tags("agent-runtime-base:v1.0.0", "production")

  tags = Template.get_tags(build.template_id)
  print(tags)
  ```
</CodeGroup>

テンプレートファミリーには名前を使用し、リリースマーカーにはタグを使用します。これにより、ロールフォワードとロールバックのワークフローをシンプルに保てます。

## ログ記録

ビルドログは、プロビジョニングの進行状況を確認し、障害を診断するのに役立ちます。

JavaScript と TypeScript では、`Template.build(...)` に `onBuildLogs` を渡します。SDK は標準のコンソールロガーとして `defaultBuildLogger(...)` もエクスポートしています。

<CodeGroup>
  ```ts JavaScript & TypeScript icon="js" theme={"system"}
  import { Template, defaultBuildLogger } from "novita-sandbox"

  const template = Template().fromPythonImage("3.12")

  await Template.build(template, "my-logged-template", {
    onBuildLogs: defaultBuildLogger({ minLevel: "info" }),
  })
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.core import Template

  template = Template().from_python_image("3.12")

  build = Template.build(template, "my-logged-template")
  print(build.build_id)
  ```
</CodeGroup>

バックグラウンドでビルドする場合は、`Template.getBuildStatus(...)` / `Template.get_build_status(...)` を使用してステータスをポーリングし、後でログエントリを取得します。

## エラー処理

テンプレートビルドは、一般的に次のような理由で失敗することがあります。

* プライベートレジストリの認証情報が無効
* `runCmd(...)` / `run_cmd(...)` 内でのパッケージインストール失敗
* start コマンドが予期せず終了する
* ready コマンドが成功しないままになる
* CPU とメモリの設定がプラットフォームの制限を満たしていない

ビルドが失敗した場合:

1. まずビルドログを確認する
2. テンプレートのソースイメージまたは Dockerfile を検証する
3. 古いレイヤーが疑われる場合は、キャッシュを無効にして再実行する
4. テンプレートを、失敗する最小の命令シーケンスまで縮小する

非同期ビルドフローでは、返されたビルドステータスを確認します。SDK は、`building`、`waiting`、`ready`、`error` などのステータスを公開しています。