Docker Compose のデプロイメント

このページでは、Docker Compose を使った Hagicode のデプロイ方法を説明します。サーバー、NAS、チームでの共有、環境の分離が必要な場面に適しています。個人のローカル環境で使う場合は、まず Microsoft Store または Desktop を検討してください。

Docker Compose を選ぶ理由

• 環境が分離されるため、依存関係の競合が起きにくくなります
• 現在サポートされている Hagicode のサービス構成を一度に起動できます
• 設定、アップグレード、メンテナンスの方法が統一されます
• ホストマシンに必要なのは Docker だけで、Node.js や Git を別途インストールする必要はありません

既定のデータストレージについて

現在サポートされている Docker Compose テンプレートは、既定のローカル SQLite データパスに沿って永続データを構成しています。ほとんどの場合、ホストマシン上に独立したデータベースサービスを別途用意する必要はありません。

ビデオチュートリアル

最初に全体の流れを確認したい場合は、ビデオチュートリアルをご覧ください。

Bilibili でビデオチュートリアルを見る

ビデオの内容:

• Docker Compose デプロイの全体の流れのデモ
• 設定ファイルの生成と変更の手順
• サービスの起動と確認の手順
• よくある問題と解決策

動画の長さ: 約 15 分

前提条件

始める前に、お使いのシステムに Docker と Docker Compose がインストールされていることを確認してください。

Docker のインストール

Windows

Docker Desktop for Windows をダウンロードしてインストールします。インストールが完了したら、Docker Desktop が実行中であることを確認してください。

macOS

Docker Desktop for Mac をダウンロードしてインストールします。インストールが完了したら、Docker Desktop が実行中であることを確認してください。

Linux

お使いのディストリビューション向けに、Docker 公式ドキュメントに従って Docker Engine と Docker Compose プラグインをインストールしてください: Install Docker Engine。ディストリビューションごとにパッケージのリポジトリやパッケージ名が異なるため、他のディストリビューション向けのコマンドをそのまま使用しないでください。

インストールが完了したら、Docker サービスを起動し、起動時に自動で開始されるよう設定します。

sudo systemctl start docker
sudo systemctl enable docker

インストールの確認

インストールが完了したら、次のコマンドを実行して、Docker と Docker Compose が正しくインストールされていることを確認します。

docker --version
docker compose version

クイックスタート

1. Docker Compose 設定ファイルの生成

Docker Compose Builder を使って docker-compose.yml を生成します。これは独立したサイトで、生成ルールと更新内容はそのサイトの内容が正となります。

ジェネレーターは次の機能をサポートしています。

• API プロバイダー (Zhipu AI、Anthropic 公式、カスタム API) の選択と、API URL および Token の設定
• ポート、コンテナ名、永続化ディレクトリ、作業ディレクトリのカスタマイズ
• 内蔵データベースまたは外部データベースの選択
• Windows / Linux のプラットフォームの違いや、よくあるファイル権限の問題への自動対応
• サポートされている Docker Hub イメージの利用

手順:

1. Docker Compose Builder を開きます。
2. 必要に応じて設定を入力します。API プロバイダーを選択し、ポート、データベース、作業ディレクトリなどのオプションを設定します。
3. 生成ボタンをクリックして、docker-compose.yml の設定を取得します。
4. 生成された設定を docker-compose.yml ファイルとして保存します。
5. 必要に応じて .env ファイルを作成して機密情報を設定し、Token を compose ファイルに直接書き込まないようにします。

イメージの入手元

ジェネレーターは、サポートされているイメージの入手元として Docker Hub を使用します。

• イメージのアドレス: newbe36524/hagicode:{tag}
• 該当するシナリオ: Docker Hub のミラーアクセラレーションを利用できるユーザーに適しています
• 注意事項: 地域によっては、ミラーアクセラレーターの設定が必要になる場合があります

API Token の取得

Docker デプロイでは、ジェネレーターで設定した API プロバイダーを通じてモデルにアクセスします。あらかじめ利用可能な API Token を用意してください。

Zhipu AI: API Token を取得 →

• 中国国内から安定してアクセスでき、応答も速い
• コストパフォーマンスが高く、日常使いに適している

Anthropic 公式: API Token を取得 →

• Anthropic のサービスを直接利用する

ジェネレーターでカスタム API を選択することもできます。

2. サービスの起動

docker-compose.yml があるディレクトリで、次のコマンドを実行します。

docker compose up -d

このコマンドは次の処理を行います。

• 生成された設定で定義されている Hagicode コンテナをダウンロードして起動する
• ネットワークを作成して構成する
• 既定のデータディレクトリとランタイムの依存関係を初期化する

3. サービス状態の確認

コンテナが実行中であるかを確認します。

docker compose ps

生成された設定で定義されたサービスが「running」状態で表示されるはずです。

サービスのログを表示します。

# すべてのサービスのログを表示
docker compose logs

# Hagicode サービスのログを表示
docker compose logs hagicode

# ログをリアルタイムで追跡
docker compose logs -f hagicode

アプリケーションへのアクセス

サービスが正常に起動したら、ブラウザから次のアドレスにアクセスします。

http://localhost:45000

ジェネレーターでポートを変更した場合は、設定したホスト側のポートを使用してください。初めて開くと初期化ウィザードが表示されます。続けて 初期化ウィザードのセットアップ を参照してください。

設定の変更

設定を変更したい場合 (ポートの変更、API プロバイダーの切り替えなど) は、次のいずれかの方法で行えます。

1. Docker Compose Builder を使って新しい設定を生成し直す
2. docker-compose.yml と .env ファイルを手動で編集する
3. コンテナを再作成して、設定を反映させる

docker compose up -d

docker compose restart は既存のコンテナを再起動するだけで、docker-compose.yml や .env の変更は反映されません。設定を変更したあとは docker compose up -d を使用してください。

データの永続化

現在サポートされている Docker Compose の構成では、既定で SQLite のデータファイルと永続ボリュームを使用します。データのマウント先やバックアップ方針を確認したい場合は、生成された docker-compose.yml にあるボリュームとデータディレクトリのマッピング設定を直接確認してください。

日常のメンテナンス

停止と起動

# サービスを停止 (コンテナとデータは保持)
docker compose stop

# 再び起動
docker compose start

# 停止してコンテナを削除 (データボリュームは保持される)
docker compose down

docker compose down に安易に -v を付けないでください。compose ファイルで宣言されたデータボリュームも一緒に削除されます。

バージョンのアップグレード

1. アップグレードの前に、データディレクトリをバックアップします (後述)。
2. docker-compose.yml のイメージタグ newbe36524/hagicode:{tag} を目的のバージョンに変更するか、ジェネレーターで設定を生成し直します。
3. 新しいイメージを取得して、コンテナを再作成します。

docker compose pull
docker compose up -d

データのバックアップ

まず docker compose stop を実行してサービスの書き込みを止め、docker-compose.yml のボリュームとデータディレクトリのマッピングに対応するディレクトリまたはデータボリュームをバックアップします。そのあと docker compose start を実行してサービスを再開します。

次のステップ

これで Hagicode のデプロイが完了しました。続けて次の手順に進んでください。

1. 初期化ウィザードのセットアップ を読み、デフォルトの Hagicoder と最初のプロジェクトを作成します。
2. 会話セッションの作成 で、まず読み取り専用モードでプロジェクトを把握し、必要に応じて 提案セッションの作成 に進みます。

デスクトップアプリケーションを使いたい場合は、Desktop インストールガイド を参照してください。