Docker Compose によるデプロイ

千桐テクノロジー2026/11/01約4分デプロイDocker Composeオープンソース版

はじめに

対象読者

Docker の基本コマンドを理解し、qOntology オープンソース版を 1 台に初回デプロイする方、または起動・停止・障害調査のコマンドを確認する方を対象とします。

デプロイ前の確認

ホストからイメージレジストリにアクセスでき、Docker で Linux コンテナーを実行できること、Compose が 2.23.2 以上であることを確認します。
イメージ、フロントエンド、SQL、設定は同一リリースを使用します。全イメージのアーキテクチャをホストに合わせ、データ量と同時実行数に応じたメモリ・ディスクを確保してください。
本文は初回デプロイ用です。既存の業務データがある環境は、先にバックアップしてアップグレード計画に従ってください。

本ガイドでは、環境変数、Docker Compose 定義、初期化 SQL、アプリケーション設定、ビルド済みフロントエンドを含む完全なデプロイパッケージを使用します。標準構成は MySQL、Redis、Neo4j、kkFileView、qOntology API、Nginx です。

コマンドの実行場所

特に記載がない限り、展開したパッケージの docker/ ディレクトリで実行し、-p qontology --profile all を維持してください。既存環境は元のプロジェクト名を使用します。<SERVER_IP> や /path/to/ は実際の値に置き換えます。

デプロイの流れ

ホストの OS に対応した手順 1 を実施し、共通の手順 2～4（パッケージのダウンロード・展開、サービス起動、アクセス）を順番に進めます。

手順 1：Docker と Docker Compose のインストール

Linux

使用するディストリビューション向けの Docker Engine インストール手順に従い、Engine と Compose プラグインをインストールします。サーバーの端末で実行してください。

docker version
docker compose version
docker info

確認基準： Client／Server の両方に接続でき、Compose ≥ 2.23.2 であること。ホストのメモリ、空きディスク、イメージのアーキテクチャも確認します。

macOS

Intel または Apple Silicon に対応する Docker Desktop for Mac をインストールします。Docker を起動してエンジンの準備を待ちます。Compose は Desktop に含まれています。ターミナルで実行してください。

docker version
docker compose version
docker info

確認基準： Client／Server の両方に接続でき、Compose ≥ 2.23.2 であること。Docker Desktop のリソース割り当てとディスク容量も確認します。

Windows

Docker Desktop for Windows をインストールし、ウィザードに従ってシステムを設定して Linux コンテナーを使用します。Docker を起動してエンジンの準備を待ちます。Compose は同梱されています。PowerShell で実行してください。

docker version
docker compose version
docker info

確認基準： Client／Server の両方に接続でき、Compose ≥ 2.23.2 であること。Docker Desktop のリソース割り当てとディスク容量も確認します。

手順 2：デプロイパッケージのダウンロードと展開

🔗 デプロイパッケージの URL： https://pan.baidu.com/s/1Lw8a4GX2G0m2c7u9CfAC9g
🔑 ダウンロード用コード： QQ グループに参加し、グループ内のファイルで確認してください。
💬 QQ グループの参加先： QQ グループに参加

完全なパッケージをダウンロード・展開し、docker/ フォルダーを取得します。Linux、macOS、Windows のいずれでも必要です。隠しファイル .env とディレクトリ構成を維持してください。

以下のファイルが含まれることを確認します。フロントエンドは同梱されています。

docker/                              # 以降の Compose コマンドの実行場所
├── .env                             # イメージ、パスワード、ポートの初期設定
├── docker-compose.yml               # メイン定義
├── docker-compose-base.yml          # ミドルウェアと Nginx
├── docker-compose-qontology.yml     # API
└── qOntology/
    ├── mysql/                       # conf.d/my.cnf、init/*.sql
    ├── nginx/                       # dist/index.html、nginx.conf、sites/
    └── server/                      # application.yml、application-prod.yml、upload/

手順 3：qOntology の起動

3.1. デプロイディレクトリへ移動

Linux／macOS： 端末で展開した docker/ に移動します。例のパスを実際の場所に置き換えてください。

cd "/path/to/docker"

Windows： エクスプローラーで展開した docker を開き、アドレスバーに powershell と入力して Enter を押すと、その場所で端末が開きます。

現在のディレクトリに .env と docker-compose.yml があることを確認し、以降もそこで実行します。

3.2. 標準設定で起動

完全パッケージは通常、起動前の設定編集なしで標準構成を使用できます。端末または PowerShell で実行します。

docker compose -p qontology --profile all up -d
docker compose -p qontology --profile all ps -a

初回起動では不足するイメージを取得し、コンテナーを作成し、空の MySQL データディレクトリに初期化 SQL を実行します。ダウンロードと初期化の完了を待ってください。所要時間はネットワークとホスト性能によります。

3.3. サービスの準備状態を確認

一覧に mysql57、redis、neo4j、kkfileview、qontology-api、nginx が含まれることを確認します。ミドルウェアが healthy、API と Nginx が継続稼働してから手順 4 に進んでください。

起動状況を確認する場合は実行します。

docker compose -p qontology --profile all logs -f --tail=200 qontology-api nginx

API ログで起動完了を確認し、接続・認証エラーが繰り返されていないことを確認します。Ctrl+C はログ表示を終了するだけで、コンテナーは停止しません。Up だけでは準備完了とは限りません。失敗が続く場合は「よくある問題」を参照してください。

初期化は新規環境専用

既存のデータディレクトリでは初期化 SQL は自動再実行されません。業務データベースへの再インポートや、業務データをリセットする reset.sh の実行は避けてください。

手順 4：qOntology へのアクセス

デプロイ完了後のアクセス

アクセス URL： http://<SERVER_IP>:8897
初期アカウント： qOntology
初期パスワード： qOntology123

デプロイ先自身からアクセスする場合は <SERVER_IP> を localhost にできます。アカウント情報はパッケージの初期化バージョンを基準としてください。入口ポートを変更した場合はその値を使用し、初回ログイン後にパスワードを変更します。

サーバーからトップページと CAPTCHA エンドポイントを確認することもできます。

curl -I http://127.0.0.1:8897/
curl -fsS http://127.0.0.1:8897/prod-api/captchaImage

Windows PowerShell では curl を curl.exe に置き換えます。トップページが正常応答し、CAPTCHA が業務 JSON を返すことを確認してください。

ログイン後に次を確認します。

検証項目	合格基準
ログインとプロジェクト管理	ログインとメニュー表示ができ、権限に応じてテストプロジェクトを作成・検索できる
アップロード・ダウンロード・プレビュー	小さいファイルをアップロード後に検索・取得でき、`/kkfileview/` で正常にプレビューできる
グラフ（任意）	自作テストデータで読み書きを確認。本手順は `neo4j-init` のサンプルを自動復元しない
AI（任意）	有効なモデル・認証情報で呼び出せる。ベクトル有効時は保存・検索も個別確認

よく使う運用コマンド

# 状態とログ。必要に応じてサービス名を mysql57、redis、neo4j などに変更
docker compose -p qontology --profile all ps -a
docker compose -p qontology --profile all logs --tail=200 qontology-api nginx
# コンテナーとデータを保持する通常の停止・再開
docker compose -p qontology --profile all stop
docker compose -p qontology --profile all start

.env や Compose の環境変数変更後、restart だけでは新設定は反映されません。影響するサービスを再作成してください。API のみ変更した場合の例です。

docker compose -p qontology --profile all up -d --no-deps --force-recreate qontology-api
docker compose -p qontology --profile all exec nginx nginx -t
docker compose -p qontology --profile all exec nginx nginx -s reload

更新前にデータベース、グラフデータ、アップロードファイル、設定をバックアップします。マウントとバックアップを確認するまで down -v やボリューム削除を実行しないでください。通常の停止は stop を使用します。

よくある問題

現象	確認方法
Compose がない／`include` 非対応	プラグインとバージョンを確認。`docker compose -p qontology --profile all config -q` で検証
イメージ取得失敗	レジストリ権限、名前、タグ、アーキテクチャを確認。対応しないバージョンで代用しない
ミドルウェアが `unhealthy`	該当ログを確認。パスワード変更後はサービス認証、API 設定、ヘルスチェックの一致を確認
白画面、403、502	`qOntology/nginx/dist/index.html` を確認。3.3 節の API ログと `docker compose -p qontology --profile all exec nginx nginx -t` を確認
`host not found in upstream`	API と kkFileView の準備状態を確認。エラー継続時は `docker compose -p qontology --profile all restart nginx` 後に再試行
サーバー自身からのみ接続可能	入口ポート、ファイアウォール、セキュリティグループ、クライアントのネットワークを確認
アップロード成功・プレビュー失敗	kkFileView の状態、フロントエンドのプレビュー URL、コンテナーからの到達性を確認。コンテナー内の `127.0.0.1` は自身を指す
AI／グラフ設定が未反映	実際の設定読み込み先と環境変数を確認