Docker Compose で PowerRAG を WSL2 Ubuntu に入れてみた

文章目录

- この記事で分かること
- 今回の環境
- まず結論
- なぜポートを変えたのか
- 必要なもの
- [`.env` を作る](#.env を作る)
- [イメージを pull する](#イメージを pull する)
- 起動する
- 起動状態を確認する
- 初回起動で少し待つ必要があった
- 停止と再起動
- 起動後にやること
- [MinerU は今回は未設定](#MinerU は今回は未設定)
- [GPU を Docker から使う場合](#GPU を Docker から使う場合)
- よく使うコマンドまとめ
- まとめ

PowerRAG をローカルの WSL2 Ubuntu 環境に入れてみました。

最初は「Docker Compose で起動すれば終わりかな」と思っていたのですが、実際にはいくつか確認しておいたほうがいい点がありました。

特に今回ポイントになったのは次の 3 つです。

80/443 が既存の Dify nginx と衝突していた
oceanbase profile を明示して起動したほうが安定した
初回起動時に DB 初期化待ちのエラーが一時的に出た

この記事では、実際に成功した手順だけを中心にまとめます。

この記事で分かること

PowerRAG を Docker Compose で起動する手順
WSL2 Ubuntu 環境で確認した前提条件
docker/.env で変更したポート設定
oceanbase/seekdb、gotenberg も含めた起動方法
初回起動時に出たエラーと、その見方
起動後に必要になるモデル設定

今回の環境

今回使った環境は以下です。

項目	内容
OS	Ubuntu 22.04.5 LTS on WSL2
CPU	13th Gen Intel i9-13900KF
メモリ	62 GiB
GPU	RTX 4090 24 GiB
Docker	28.3.3
Docker Compose	v2.39.1
リポジトリ	`/u01/workspace/powerrag`

PowerRAG 本体を動かすだけなら、GPU は必須ではありません。

GPU が必要になるのは、MinerU、vLLM、ローカル LLM、TEI-GPU などを同じ環境で動かす場合です。

まず結論

今回の環境では、最終的にこのコマンドで起動できました。

bash 复制代码

cd /u01/workspace/powerrag/docker
docker compose pull
docker compose --profile oceanbase up -d

起動したコンテナはこの 3 つです。

text 复制代码

powerrag-powerrag-1
powerrag-oceanbase-1
powerrag-gotenberg-1

最終的にはすべて healthy になりました。

text 复制代码

powerrag-powerrag-1    healthy
powerrag-oceanbase-1   healthy
powerrag-gotenberg-1   healthy

アクセス先は以下です。

用途	URL
Web UI	`http://localhost:8080`
PowerRAG API	`http://localhost:6000`
RAGFlow API	`http://localhost:9380`
Admin API	`http://localhost:9381`
MCP API	`http://localhost:9382`
OceanBase/SeekDB	`127.0.0.1:2881`

なぜポートを変えたのか

PowerRAG の Docker Compose は、Web UI をデフォルトで 80/443 に出そうとします。

ただ、今回のマシンでは Dify の nginx コンテナがすでに 80/443 を使っていました。

そのため、PowerRAG 側は以下のように変更しました。

dotenv 复制代码

SVR_WEB_HTTP_PORT=8080
SVR_WEB_HTTPS_PORT=8443

ポートの使用状況は、事前に見ておいたほうがいいです。

bash 复制代码

ss -ltnp
docker ps

必要なもの

今回の Docker Compose 構成で必要だったものは以下です。

もの	用途
Docker / Docker Compose	コンテナ実行
`oceanbase/powerrag:v0.2.0`	PowerRAG 本体
`oceanbase/seekdb:1.0.0.0-100000262025111218`	DB / 検索ストレージ
`gotenberg/gotenberg:8`	ドキュメント変換

実際に pull 後のイメージはこうなっていました。

text 复制代码

oceanbase/powerrag:v0.2.0
oceanbase/seekdb:1.0.0.0-100000262025111218
gotenberg/gotenberg:8

`.env` を作る

まず Docker 用のディレクトリに移動します。

bash 复制代码

cd /u01/workspace/powerrag/docker

.env がない場合は、サンプルから作ります。

bash 复制代码

cp .env.example .env

今回使った主な設定は以下です。

dotenv 复制代码

COMPOSE_PROJECT_NAME=powerrag
POWERRAG_IMAGE=oceanbase/powerrag:v0.2.0

SVR_WEB_HTTP_PORT=8080
SVR_WEB_HTTPS_PORT=8443
SVR_HTTP_PORT=9380
ADMIN_SVR_HTTP_PORT=9381
SVR_MCP_PORT=9382
POWERRAG_SVR_HTTP_PORT=6000
PUBLIC_SERVER_URL=http://localhost:6000

DOC_ENGINE=oceanbase
CACHE_TYPE=oceanbase
STORAGE_IMPL=OPENDAL
COMPOSE_PROFILES=${DOC_ENGINE}

EXPOSE_OB_PORT=2881
GOTENBERG_HOST=gotenberg
GOTENBERG_PORT=3000
USE_DOCLING=false
USE_MINERU=false

ここで大事なのは、Web のポートを 8080/8443 にしている点です。

イメージを pull する

次にイメージを pull します。

bash 复制代码

cd /u01/workspace/powerrag/docker
docker compose pull

今回の環境では、特に oceanbase/powerrag:v0.2.0 が大きめでした。

pull 済みか確認するなら、以下で見ます。

bash 复制代码

docker image ls

起動する

起動は以下です。

bash 复制代码

cd /u01/workspace/powerrag/docker
docker compose --profile oceanbase up -d

.env には次の設定があります。

dotenv 复制代码

DOC_ENGINE=oceanbase
COMPOSE_PROFILES=${DOC_ENGINE}

そのため docker compose up -d でも動く場合があります。

ただ、今回のように手順を確実に残すなら、明示的に --profile oceanbase を付けたほうが分かりやすいです。

起動状態を確認する

まずコンテナを見ます。

bash 复制代码

docker ps --filter name=powerrag

今回の最終状態は以下でした。

text 复制代码

powerrag-powerrag-1    Up ... (healthy)
powerrag-gotenberg-1   Up ... (healthy)
powerrag-oceanbase-1   Up ... (healthy)

PowerRAG API を確認します。

bash 复制代码

curl -f http://localhost:6000/health

成功すると、以下のように返ります。

json 复制代码

{"status":"ok","service":"powerrag"}

RAGFlow 側も確認します。

bash 复制代码

curl -f http://localhost:9380/v1/system/healthz

成功すると、以下のように返ります。

json 复制代码

{"db":"ok","doc_engine":"ok","redis":"ok","status":"ok","storage":"ok"}

Web UI は 8080 です。

bash 复制代码

curl -I http://localhost:8080

200 OK が返れば、ブラウザから開けます。

text 复制代码

http://localhost:8080

初回起動で少し待つ必要があった

初回起動直後は、powerrag がしばらく health: starting になっていました。

これは DB の初期化、RAGFlow のテーブル作成、PowerRAG サーバーの起動が並行して走るためです。

ログは以下で見ます。

bash 复制代码

cd /u01/workspace/powerrag/docker
docker compose logs -f powerrag

今回、途中で以下のようなエラーが出ました。

text 复制代码

Table 'powerrag.user' doesn't exist

最初は失敗したように見えます。

ただ、これは admin_server が ragflow_server の DB 初期化完了より先に起動してしまったための一時的なエラーでした。

少し待つと、最終的には以下のように健康チェックが通りました。

bash 复制代码

curl -f http://localhost:6000/health
curl -f http://localhost:9380/v1/system/healthz

つまり、このエラーが出ても、すぐに volume を消したり再構築したりしないほうがいいです。

まずはログを見ながら数分待つのがよさそうです。

停止と再起動

停止する場合は、データを残すために普通の down を使います。

bash 复制代码

cd /u01/workspace/powerrag/docker
docker compose --profile oceanbase down

再起動は以下です。

bash 复制代码

cd /u01/workspace/powerrag/docker
docker compose --profile oceanbase up -d

または restart でもよいです。

bash 复制代码

docker compose --profile oceanbase restart

注意点として、気軽に -v を付けないほうがいいです。

bash 复制代码

docker compose down -v

これは DB やログ、履歴データの volume も消します。

検証環境ならともかく、作ったデータを残したい場合は避けたほうがいいです。

起動後にやること

ここまでで PowerRAG のサービス自体は起動します。

ただし、これだけでは知識ベースの処理やチャットはまだ完全には使えません。

Web UI で最低限、以下を設定する必要があります。

Chat モデル
Embedding モデル
必要に応じて Rerank モデル

特に Embedding モデルがないと、知識ベースのベクトル化や検索が進みません。

「コンテナは healthy なのに機能が動かない」という場合は、まずモデル設定を確認したほうがいいです。

MinerU は今回は未設定

今回の起動確認では MinerU は有効にしていません。

dotenv 复制代码

USE_MINERU=false

PowerRAG の複雑な PDF 解析や OCR を使うなら、あとから MinerU API を接続するのがよさそうです。

たとえば、宿主機側に MinerU API が 8000 で立っているなら、コンテナからは host.docker.internal を使います。

dotenv 复制代码

USE_MINERU=true
MINERU_API_URL=http://host.docker.internal:8000
MINERU_BACKEND=pipeline
MINERU_VLM_URL=

vLLM バックエンドを使う場合は、たとえば以下のようになります。

dotenv 复制代码

USE_MINERU=true
MINERU_API_URL=http://host.docker.internal:8000
MINERU_BACKEND=vlm-http-client
MINERU_VLM_URL=http://host.docker.internal:30000

ここで注意したいのは、Gradio UI が動いていることと、PowerRAG が期待する MinerU API が動いていることは別だという点です。

接続前に、API として見えるか確認したほうがいいです。

bash 复制代码

curl -f http://localhost:8000/health
curl -f http://localhost:8000/openapi.json

GPU を Docker から使う場合

PowerRAG 本体の起動だけなら、GPU は必須ではありません。

ただし、MinerU vLLM、ローカル LLM、TEI-GPU などを Docker 内で動かすなら、GPU コンテナの確認が必要です。

bash 复制代码

docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

これが失敗する場合は、PowerRAG ではなく Docker と NVIDIA Container Toolkit 側の問題です。

まずは PowerRAG 本体を CPU のまま起動して、その後で GPU 周りを切り分けるほうが進めやすいです。

よく使うコマンドまとめ

bash 复制代码

# docker ディレクトリへ移動
cd /u01/workspace/powerrag/docker

# イメージ取得
docker compose pull

# 起動
docker compose --profile oceanbase up -d

# 状態確認
docker compose ps
docker ps --filter name=powerrag

# ログ確認
docker compose logs -f powerrag

# 健康チェック
curl -f http://localhost:6000/health
curl -f http://localhost:9380/v1/system/healthz
curl -I http://localhost:8080

# 停止
docker compose --profile oceanbase down

まとめ

PowerRAG は Docker Compose で比較的素直に起動できました。

ただし、実際に入れてみると、見るべき点はいくつかありました。

既存サービスとのポート衝突
oceanbase profile の明示
初回 DB 初期化中の一時的なエラー
起動後の Chat / Embedding モデル設定
MinerU や GPU は別途切り分け

今回の環境では、最終的に以下の流れで安定しました。

bash 复制代码

cd /u01/workspace/powerrag/docker
docker compose pull
docker compose --profile oceanbase up -d

Web UI はここです。

text 复制代码

http://localhost:8080

まずはこの状態まで持っていき、そのあとモデル設定や MinerU 連携を進めるのがよさそうです。

Docker Compose で PowerRAG を WSL2 Ubuntu に入れてみた

文章目录

この記事で分かること

今回の環境

まず結論

なぜポートを変えたのか

必要なもの

.env を作る

イメージを pull する

起動する

起動状態を確認する

初回起動で少し待つ必要があった

停止と再起動

起動後にやること

MinerU は今回は未設定

GPU を Docker から使う場合

よく使うコマンドまとめ

まとめ

`.env` を作る