BullMQ による Producer/Consumer 実装サンプル
このプロジェクトは、BullMQ を使用した非同期ジョブキューシステムの実装例です。 Dockerコンテナを使用して Producer（ジョブ投入）と Consumer（ジョブ処理）を分離し、Redis を介した本格的なジョブキュー処理を実演します。
Vagrant + Ansible により Ubuntu 24.04 上に Docker 環境を自動構築し、すぐに BullMQ の動作を試すことができます。
Client → nginx → nodejs (Producer) → Redis (BullMQ) → worker (Consumer)
- nodejs コンテナ (Producer): HTTP API でジョブを受け付け、Redis キューに投入
- worker コンテナ (Consumer): バックグラウンドでジョブを取得・処理
- redis コンテナ: BullMQ のジョブキューを管理
- OS: Ubuntu 24.04 (bento/ubuntu-24.04)
- Docker: geerlingguy.docker ロールによるインストール
- ジョブキュー: BullMQ v5 (Node.js v24 + TypeScript)
- タイムゾーン: Asia/Tokyo
- SSL/TLS: 自己署名証明書によるHTTPS接続
| コンテナ | 役割 | 説明 |
|---|---|---|
| nodejs | Producer | Node.js v24 - HTTP API でジョブを受け付け BullMQ に投入 |
| worker | Consumer | Node.js v24 - BullMQ からジョブを取得して非同期処理 |
| redis | Queue Store | BullMQ のジョブキュー・状態管理 |
| nginx | Reverse Proxy | リバースプロキシ/Webサーバー（HTTPS対応） |
| mariadb | Database | データベースサーバー（必要に応じて利用） |
- クライアントが HTTP リクエストでジョブを投入
- Producer (nodejs) が BullMQ Queue にジョブを追加
- Redis にジョブデータが永続化
- Consumer (worker) がジョブを検知して取得
- バックグラウンドで処理を実行
- 処理結果を記録
詳細な実装は playbooks/app/README.md を参照してください。
- VirtualBox がインストールされていること
- Vagrant がインストールされていること
- 十分なメモリ（最低2GB）と空きディスク容量があること
.
├── README.md # このファイル
├── Vagrantfile # Vagrant設定ファイル
└── playbooks/ # Ansibleプレイブック
├── main.yml # メインプレイブック
├── requirements.yml # 必要なロールの定義
├── app/ # BullMQ ジョブキューアプリケーション
│ ├── package.json # 依存関係定義（BullMQ, Express等）
│ ├── tsconfig.json # TypeScript設定
│ ├── README.md # BullMQ実装の詳細説明
│ └── src/
│ ├── main.ts # Producer - HTTP API でジョブ投入
│ ├── consumer.ts # Consumer - バックグラウンド処理
│ ├── config.ts # Redis接続設定
│ └── queue/ # BullMQ キュー定義・実装
├── vars/ # 変数定義
│ └── main.yml # メイン変数ファイル
├── tasks/ # タスク定義
│ ├── japanese.yml # 日本語環境設定
│ ├── redis.yml # Redisコンテナ構築（BullMQ用）
│ ├── mariadb.yml # MariaDBコンテナ構築
│ ├── nginx.yml # Nginxコンテナ構築
│ ├── nodejs.yml # Node.jsコンテナ構築（Producer）
│ ├── worker.yml # Workerコンテナ構築（Consumer）
│ └── app.yml # アプリケーションデプロイ
└── containers/ # コンテナ設定
├── mariadb/ # MariaDB用Dockerfile等
├── nginx/ # Nginx用設定ファイル等
├── nodejs/ # Node.js用Dockerfile等（Producer/Consumer共通）
└── redis/ # Redis用Dockerfile等（BullMQ用）
仮想マシンには固定IPアドレス 192.168.33.10 が設定されます。
必要に応じて Vagrantfile の config.vm.network の設定を変更してください。
- リポジトリをクローンする
- 以下のコマンドを実行してVirtualBox上に環境を構築
vagrant up環境構築後、以下のいずれかの方法で仮想マシンに接続できます。
- Vagrantから接続:
vagrant ssh- SSHで直接接続:
※デフォルトパスワード: vagrant
接続後、以下のコマンドでrootユーザーに切り替えることができます。
sudo su -環境構築後、仮想マシン内で以下のコマンドでコンテナの状態を確認できます。
docker ps # 実行中のコンテナ一覧
docker logs nodejs # Producer - ジョブ投入ログ
docker logs worker # Consumer - ジョブ処理ログ
docker logs redis # BullMQ キューストアのログ
docker logs nginx # リバースプロキシのログ
docker logs mariadb # データベースのログMariaDBの初期設定は以下の通りです（playbooks/vars/main.yml で変更可能）:
| 項目 | 値 |
|---|---|
| rootパスワード | root_password |
| データベース名 | sample-db |
| ユーザー名 | sample_user |
| パスワード | sample_password |
playbooks/vars/main.ymlを編集することで、コンテナ名やDB設定を変更できますplaybooks/main.ymlを編集することで、追加のパッケージやタスクを追加できますVagrantfileのvb.memoryを編集して、仮想マシンのメモリ割り当てを変更できます
この環境では、NginxがHTTPS（ポート443）でリッスンし、自己署名SSL証明書を使用してセキュアな接続を提供します。
HTTPポート（80）へのアクセスは自動的にHTTPS（443）にリダイレクトされます。
自己署名証明書を使用しているため、ブラウザで初回アクセス時に「安全ではありません」という警告が表示されます。 これは開発環境では正常な動作です。以下の手順で続行できます：
- ブラウザで
https://192.168.33.10にアクセス - 「詳細設定」または「Advanced」をクリック
- 「安全ではないページに移動」または「Proceed to 192.168.33.10 (unsafe)」をクリック
playbooks/app ディレクトリに Express + BullMQ + TypeScript を使用した Producer/Consumer サンプルが含まれています。
- ✅ Producer: HTTP API エンドポイントでジョブを受け付け
- ✅ Consumer: バックグラウンドでジョブを非同期処理
- ✅ TypeScript: 型安全な実装
- ✅ 美しい UI: テスト用 Web インターフェース
ブラウザからジョブを投入:
http://192.168.33.10/
美しいUIのテストページが表示され、メッセージを入力して BullMQ ジョブキューの動作をテストできます。
ログでジョブ処理を確認:
vagrant ssh
# Producer（ジョブ投入）のログ
docker logs -f nodejs
# Consumer（ジョブ処理）のログ
docker logs -f workerリアルタイムでジョブの投入と処理の様子を確認できます。
playbooks/app ディレクトリの内容を置き換えるか、以下の要件を満たすアプリケーションを配置してください：
package.jsonにstartスクリプトが定義されていること- ポート 3000 でリッスンすること
- pnpm を使用すること
- BullMQ の接続先として環境変数
REDIS_HOSTを使用すること
ネットワーク設定に問題が発生した場合は、Vagrantfile の IPアドレスを
使用環境に合わせて変更してください。
VirtualBoxの設定や競合を確認し、必要に応じてVirtualBoxを再起動してください。
vagrant provision