NocoBase を Docker Compose でローカルで動かしてみよう！ 公式手順だけでは見落とす、後から変えにくい設定
はじめに
杉浦です。NocoBase シリーズの第3回です。
第1回で NocoBase の考え方を、第2回で 2.x の主要機能を整理しました。ここからは実際に動かしていきます。
今回は Docker Compose でローカルに立てて、管理画面に入るところまでです。手順そのものは公式ドキュメントに記述があります。ただし、compose ファイルを作る時点で、後から変えにくい設定をいくつか決めていることは、手順を追うだけでは見落としがちです。バージョン、データベース、タイムゾーン、それにデータの置き場です。この記事ではそこに時間を使います。
なお、ここで作った環境は第4回でそのまま使います。消さずに残しておいてください。
前提
- Docker と Docker Compose が動くこと
- Docker が起動していること
公式の前提もこの2つだけです（Docker Installation）。
この記事は次の環境で確認しました。
- NocoBase v2.2.5（OSS 版・
-fullイメージ） - PostgreSQL 16
- Docker Compose v2
- Windows 11 + WSL2（Debian）+ Rancher Desktop
docker-compose.yml を作る
公式ドキュメントに PostgreSQL / MySQL / MariaDB それぞれの設定例が載っています。PostgreSQL の例をベースに、選択が要る箇所を順に見ていきます。
networks:
nocobase:
driver: bridge
services:
app:
image: nocobase/nocobase:2.2.5-full
restart: always
networks:
- nocobase
depends_on:
- postgres
environment:
- APP_KEY=ここをランダムな文字列に置き換える
- DB_DIALECT=postgres
- DB_HOST=postgres
- DB_PORT=5432
- DB_DATABASE=nocobase
- DB_USER=nocobase
- DB_PASSWORD=nocobase
- TZ=Asia/Tokyo
volumes:
- storage:/app/nocobase/storage
ports:
- '13000:80'
postgres:
image: postgres:16
restart: always
command: postgres -c wal_level=logical
environment:
POSTGRES_USER: nocobase
POSTGRES_DB: nocobase
POSTGRES_PASSWORD: nocobase
volumes:
- pgdata:/var/lib/postgresql/data
networks:
- nocobase
volumes:
storage:
pgdata:
公式の例から変えたのは、イメージのタグ、タイムゾーン、ボリュームの3箇所です。postgres 側の wal_level=logical は公式の例にそのまま入っているもので、ここでは触れません。理由を順に説明します。
イメージのタグを数字で固定する
公式の例は nocobase/nocobase:latest-full になっています。ここを 2.2.5-full のようにバージョン番号で指定することをおすすめします。公式ドキュメントにも、本番環境について同じ趣旨の記述があります。
本番環境では、意図しない自動アップグレードを避けるため、特定の数字バージョンに固定することをお勧めします。
第2回で触れたとおり、NocoBase はパッチが数日おきに出ます。latest のままだと、イメージを取り直したタイミングで意図せずバージョンが上がります。
なお、npm に公開された版が Docker Hub にも必ずあるとは限りません。この記事の公開時点では、npm の最新は 2.2.8 で Docker Hub にも 2.2.8-full がありますが、その途中の 2.2.6 は Docker Hub に存在しません（2.2.5-full の次は 2.2.7-full）。 使いたい版のタグが Docker Hub に存在するかは、タグ一覧で確認しておくと安心です。この記事の compose では、動作を確認した 2.2.5 を指定しています。新しい版があれば置き換えて構いません。
そして NocoBase はバージョンを戻せません。試しに、2.2.5 で作った環境のタグを 2.1.44 に変更して起動してみました。コンテナは立ち上がり、ログインもでき、データも読めます。一見なんともないのですが、ログには次のエラーがリクエストのたびに出続けます。
Cannot find plugin '@nocobase/plugin-block-comment'
Cannot find plugin '@nocobase/plugin-ui-layout'
2.2 で追加されたプラグインの登録がデータベースに残ったまま、2.1 のイメージにはその実体が無い、という状態です。止まらないぶん、壊れていることに気づきにくいのが厄介です。
ローカルの検証環境であれば作り直せば済みますが、上げる前にバックアップを取る癖をつけておくと安心です。
-full と通常イメージの違い
タグの末尾に -full が付くものと付かないものがあります。公式ドキュメントの説明はこうです。
full イメージには、バックアップ管理、移行管理プラグインに必要な PostgreSQL 16/17 クライアント、MySQL 8.0 クライアント、Oracle 19.25 クライアント、およびテンプレート印刷（PDF）に必要な LibreOffice が含まれています
つまりプラグインの一部が動くために必要な外部コマンドが入っているかどうかの違いです。イメージのサイズは大きくなりますが、最初は -full を選んでおくほうが無難です。あとから「バックアップ機能が動かない」と気づいてイメージを差し替える手間を考えると、そのほうが早いと思います。
データベースを選ぶ
DB_DIALECT で PostgreSQL / MySQL / MariaDB を選べます。
迷うなら PostgreSQL でよいと思います。公式の設定例が PostgreSQL から始まっていて、情報を探しやすいためです。
ただし、データが入ってから別の製品に移すのは手間なので、選ぶ前に知っておきたい違いがひとつあります。日時の保存形式がデータベース製品によって変わります。
- PostgreSQL: タイムゾーン付きの日時型があり、オフセットを含む絶対時刻として保存される
- MySQL:
DATETIMEに保存され、オフセットの情報を持たない
このため、サーバーのタイムゾーン設定を後から変えたときに、保存済みデータの解釈がどうなるかが変わります。予定や履歴のように日時そのものが業務の意味を持つシステムでは、無視できない差です。
タイムゾーンを Asia/Tokyo にする
公式の設定例は、英語版が TZ=Etc/UTC、日本語版が TZ=Asia/Shanghai になっています。日本で使うなら Asia/Tokyo に変えます。
前項のとおり、これは後から変えると保存済みデータの解釈がずれる可能性がある設定です。最初に決めておくのが安全です。
APP_KEY を置き換える
APP_KEY はユーザートークンなどの暗号化に使われる鍵です。your-secret-key のままにせず、ランダムな文字列に置き換えてください。公式の設定例にも、変更すると既存のトークンが無効になる旨のコメントが入っています。
生成はたとえばこれで済みます。
openssl rand -base64 32
ボリュームは名前付きにする
公式の例では、データの置き場を ./storage のようにプロジェクト直下のディレクトリに割り当てています（バインドマウント）。ここは名前付きボリューム（storage と pgdata）に変えました。
理由は、私の環境ではその置き場が期待どおりに動かなかったからです。Rancher Desktop では ./storage がプロジェクト直下に現れず、実体は /mnt/wsl/rancher-desktop/run/docker-mounts/ 配下に置かれていました。そして docker compose down を実行するとデータが消えました。作ったコレクションが、up -d し直しても戻ってきません。
名前付きボリュームにすると、同じ操作でデータが残りました。Docker Desktop や Linux で公式の例がどう動くかは確認していませんが、名前付きボリュームなら環境を問わず残るので、こちらを選んでおくほうが無難です。
これも「後から変えにくい設定」のひとつです。データが入ってから置き場を変えるには、移し替えの作業が要ります。
ポート
'13000:80' はホスト側の 13000 番をコンテナの 80 番につないでいます。ホスト側は自由に変えられます。すでに 13000 が埋まっている場合や、複数の環境を並行して立てたい場合はここを変えてください。
起動する
compose ファイルを置いたディレクトリで起動します。
docker compose up -d
初回はイメージの取得に時間がかかります。取得が終わってコンテナが立ち上がったあとも、すぐにはアクセスできません。NocoBase はプラグインを順に読み込んでから起動を完了するためです。私の環境では、コンテナが立ち上がってから応答が返るまで 30 秒ほどでした。PC の性能や OS によって変わるので、目安として見てください。
ログで進み具合を見られます。
docker compose logs -f app
起動が終わったら http://localhost:13000 を開くと、ログイン画面が出ます。管理者アカウントを作る画面はなく、最初から既定のアカウントが用意されています。
- メールアドレス:
admin@nocobase.com - パスワード:
admin123
公式ドキュメントには、次の注意書きがあります。
初回ログイン後、システムの安全を確保するため、速やかにデフォルトパスワードを変更してください。
ローカルで試すだけでも、最初に変えておくのがよいでしょう。
ログインするとトップ画面に入れます。画面は英語で表示されます。既定で有効な言語が英語だけのためです。日本語にするには、右上の歯車アイコンから System settings を開き、Enabled languages に「日本語 (ja-JP)」を追加して Submit します。一覧の先頭にある言語が既定になる（(Default) と付く）ので、英語を外して日本語だけにすれば、次の画面から日本語で表示されます。
なお、日本語にしても AI employees や License settings など一部のメニューは英語のままです。プラグイン側に日本語の翻訳が用意されていないためで、第2回で触れた UI テンプレートの操作名が英語のままなのと同じ事情です。
ログイン直後はページが1つも無く、右上の UI エディタから設定を始めるよう案内が出ます。ここから先は第1回で触れた「テーブルを作って画面に配置する」の世界で、第4回で実際に作っていきます。
立てたあとの基本操作
止める・再開する
docker compose stop # 止める（データはそのまま）
docker compose start # 再開する
NocoBase 本体とデータベースを合わせるとそれなりにメモリを使うので、使わないときは止めておくとよいでしょう。私は同時に複数の環境を立ち上げないようにしています。
作り直す
docker compose down # コンテナとネットワークを削除（ボリュームは残る）
docker compose down -v # ボリュームごと削除（データも消える）
down はコンテナを消しますが、名前付きボリュームは残ります。down してから up -d すればデータは戻ってきます。
完全にまっさらから始めたい場合は down -v で、ボリュームごと消します。この操作でデータベースの中身も消えますので、実行前に中身を確認してください。
バージョンを上げる
イメージのタグを変更してから取り直します。
docker compose pull app
docker compose up -d
起動時にマイグレーションが自動で適用されます。上げる前にバックアップを取ってください。前述のとおり、戻すのは簡単ではありません。
つまずきやすいところ
ポートが埋まっているとき。 docker compose up -d がポート関連のエラーで失敗する場合は、compose ファイルのホスト側ポートを変えてください。
メモリ。 アプリとデータベースを合わせた消費量は小さくありません。私の環境では、起動直後の何も入っていない状態で、アプリが約 670MB、PostgreSQL が約 90MB でした（docker stats の値）。こちらも PC の性能や OS で変わります。
起動を待つ。 コンテナが Up になっていてもアプリはまだ準備中のことがあります。ブラウザでエラーが出たら、ログを見て起動完了を待ってください。
次回以降の予定
次の2回は、この順で進める予定です（あくまで予定なので、順番も内容も変わるかもしれません）。
- 第4回（仮）: 最初の業務アプリを作ってみる。蔵書管理を題材に、コレクションを定義して画面に配置するまで
- 第5回（仮）: 権限を付けてみる。ロールを作り、見える範囲とできる操作を分ける
第4回では、今回立てた環境をそのまま使います。日本語化と既定パスワードの変更を済ませた状態で残しておいてください。
まとめ
- Docker Compose で立てるだけなら、公式の設定例をコピーして数箇所を変更するだけで済みます
- 手を入れる箇所は イメージのタグ・タイムゾーン・APP_KEY・ボリューム の4つです
- そのうちバージョン、タイムゾーン、ボリュームの置き場、それにデータベース製品は、後から変えにくい設定です。立てる前に決めておくと、あとで困りません
- ローカル環境は作り直せますが、上げる前のバックアップを習慣にしておくと、戻せないことを怖がらずに済みます
次回はこの環境の上に、実際に業務アプリを作っていきます。日本語化とパスワード変更を済ませて、そのまま残しておいてください。
