インストール

ngx_mrubyを組み込んだnginxで、インラインとファイルのRubyを実行します。root権限を使わず、ループバックだけで試します。

対象はnext開発ブランチとnginx 1.31.8です。安定リリースではありません。リリース済みの2.xには、安定版の導入手順を使ってください。結果を比較する前に、ソースのコミットとビルド設定を記録します。Dockerで先に試すには、はじめにの例を使えます。既存環境の更新前にはリリースノートを確認してください。

ソースからインストールする

前提

C/C++コンパイラ、GNU make、Rubyとrake、bison、git、wget、curlが必要です。OpenSSL・PCRE・zlibは開発用ヘッダとライブラリも用意します。ビルドはGitHubからサードパーティのmrbgemsを取得します。Docker Hubのアカウントは不要です。

Ubuntu 22.04では、まず管理者権限でパッケージを入れます。以降のビルドは一般ユーザーで行ってください。

sudo apt-get update
sudo apt-get install build-essential ruby rake bison git wget curl ca-certificates libssl-dev libpcre3-dev zlib1g-dev

この手順の対象はLinuxです。他のOSではパッケージ名が異なります。バージョン管理ツールでRubyを選ぶ場合は、そのrubyとrakeをPATHに含めてください。

動的モジュールとnginxの版・設定・ABIは一致が必要です。無関係な配布版へのコピーは避けてください。

1. github.comからソースを取得する

git clone --branch next https://github.com/matsumotory/ngx_mruby.git
cd ngx_mruby
git rev-parse HEAD

nextは開発PRのマージで進みます。git rev-parse HEADで使用したコミットを記録してください。過去のビルドを再現するときは、ビルド前にそのコミットをチェックアウトします。

mrubyのソースと、後述するサードパーティgemのロックはリポジトリに含まれます。ただし、ロックは外部取得をすべて固定するものではなく、バイナリの完全一致を保証しません。

2. mrbgemsを設定する

build_config.rbには、ビルドがmrubyに入れるmrbgemsが書いてあります。NGX_MRUBY_CORE_GEMSのmrubyのコアのgemと、サードパーティのgemです。コアのgemの説明はコアのgemにあります。ビルドのリファレンスのデフォルトのmrbgemsには、デフォルトのビルドに入るサードパーティのgemと、それぞれが加えるクラスがあります。gemを加えるには、build_config.rbのhostのビルドにconf.gemの行を足します。ほかのgemは、mrubyのmrbgemsの一覧にあります。build_config.rbでコメントになっている行には、mruby-discountやmruby-memcachedのような、デフォルトのビルドが入れないgemの名前があります。そのgemを入れてビルドするには、行のコメントを外してください。

NGX_MRUBY_CORE_GEMSが挙げるgemが、ビルドするmrubyのmrbgemsディレクトリに無いと、mrubyのビルドは止まります。たとえば、./configure --with-mruby-rootで別のバージョンのmrubyを指定したときです。一覧を書き換えるか、mrubyのビルドの環境でNGX_MRUBY_ALLOW_MISSING_CORE_GEMS=1を設定して、通知を出してそれらのgemを飛ばしてください。

mruby-ioはデフォルトに含まれます。ファイル・ソケット・sleep・Redisの処理は、workerをブロックする場合があります。

同梱gemでも、nginxのイベント処理に対応するとは限りません。各APIの制約はリファレンスにあります。

3.0.0ではauto-sslを除外しました。auto-sslのmrbgemと、それと一緒に入っていたクラスで移行手順を説明します。

コアのgem

同梱のmrubyは4.0.0です。ngx_mrubyは、mrubyのfull-core.gemboxではなく、NGX_MRUBY_CORE_GEMSが挙げるコアのgemをビルドします。こうすると、ngx_mrubyのスクリプトのクラスとメソッドは、この一覧を変えたときにだけ変わります。一覧は、mruby 3.3.0のfull-core.gemboxが選んでいたgemの集合で、違いは次のとおりです。

• mruby-printはありません。mruby 3.4で削除されました。Kernel#print、#puts、#pはmruby-ioが定義します。
• 一覧には、hal-posix-io、hal-posix-dir、hal-posix-socketがあります。mruby 4.0.0では、mruby-io、mruby-dir、mruby-socketは、このどれかのバックエンドを通してOSを使います。これらのgemは、クラスもメソッドも加えません。これらがあるのは4.0.0だけです。mruby 4.1.0-rc2では、POSIXのバックエンドはmruby-io、mruby-dir、mruby-socketの一部になり、hal-*のgemはありません。そのため、mruby 4.1への更新で、この3つの名前を一覧から消します。

mruby 4.0.0のコアのgemのうち、4.0.0のfull-core.gemboxは入れるのに、この一覧が入れないものは次のとおりです。

gem	入れると変わること	入れない理由
mruby-taskと、hal-posix-task	Taskを加え、Kernel#sleepを定義し直す。mrb_stateを開くすべてのプロセスに、SIGALRMのインターバルタイマーのsetitimerがかかる。mrb_stateは8つまでになる。上限はMRB_TASK_MAX_VMS	ワーカーのタイマーとsleepに関わる。ngx_mrubyには、Nginx::Asyncがある
mruby-encoding	ビルド全体にMRB_UTF8_STRINGを定義する。String#size、#[]、#indexなどが、バイトではなく文字を数える。String#valid_encoding?、#encoding、#force_encodingを加える	リクエストとレスポンスのデータはバイト列で、String#sizeからContent-Lengthを計算するスクリプトは、違う数を得る。オーナーは2026年10月4日に、このgemをデフォルトのビルドから外し、オプトインのままにすると決めた。外したため、mruby 3.3ではmruby-string-extが定義していたString#valid_encoding?を呼ぶと、NoMethodErrorが起きる。mruby 3.4からは、mruby-encodingだけがこのメソッドを定義する
mruby-strftime	Time#strftimeを加える	新しいAPIで、別に決める
mruby-benchmark	Benchmarkを加える	新しいAPIで、開発のツール

4.0.0のfull-core.gemboxは、mruby-sleep、mruby-bin-debugger、mruby-testを入れません。ngx_mrubyは、Kernel#sleepと#usleepを定義するmruby-sleepを残しています。

一覧に載っていないgemを入れてビルドするには、build_config.rbのNGX_MRUBY_CORE_GEMSにその名前を足し、mruby/buildを消してビルドし直してください。mruby-encodingを入れるときはリクエストやレスポンスのデータにString#size、#length、#[]、#slice、#index、#reverseを使うスクリプトをすべて確かめ、バイトを扱うところでは#bytesizeと#bytesliceを使ってください。Nginx::Utils.escapeはもともとバイトを扱います。ngx_mruby自身のテストスイートは、mruby-encodingやmruby-taskを入れたビルドでは実行しません。

String#valid_encoding?を呼ぶスクリプトでは、上の確認をしたうえでmruby-encodingを入れるか、その呼び出しを消してください。2.xのデフォルトのbuild_config.rbは、MRB_UTF8_STRINGを定義せずにmruby 3.3.0をビルドします。そのビルドでは、このメソッドはすべての文字列にtrueを返し、"\xfe"にもtrueを返しました。そのため、呼び出しを消しても、そのようなスクリプトが受け付けるものは変わりません。build_config.rbでMRB_UTF8_STRINGを定義した2.xのビルドでは、UTF-8として正しくない文字列にfalseが返りました。その確認を残すには、MRB_UTF8_STRINGとこのメソッドの両方を定義するmruby-encodingを入れてビルドしてください。

gemのコミットとbuild_config.rb.lock

build_config.rbはサードパーティのmrbgemsを指定し、その隣にコミットしたbuild_config.rb.lockは、それぞれのgemのコミットを記録します。こうすると、ngx_mrubyの同じコミットをチェックアウトすれば、どのマシンでも、後のいつでも、同じgemをビルドできるようになります。mrubyのrakeは、ビルドのたびに最後にこのファイルを書き、次のビルドの最初に読みます。

ロックにはbuild_config.rbのmrubyのビルドごとにセクションがあります。ngx_mrubyがリンクするmrubyのhostと、test.shのテストを実行するmrubyのバイナリのtestです。各セクションのエントリーは、gemのリポジトリのURLをキーにして、gemのブランチ、コミット、バージョンを記録します。エントリーがあるのは、build_config.rbがgithub:で宣言するgemと、それらが依存してrakeが一緒にクローンするgemです。たとえばhostには同梱のrack-based-apiが要るksss/mruby-stringioがあります。mruby自身のgemのmruby/mrbgems/と、mrbgems/の下の同梱のgemは、ソースツリーの一部なのでエントリーがありません。mrubyのセクションは、同梱のmrubyのバージョンを記録します。

エントリーのあるgemでは、rakeはリポジトリを履歴ごと、mruby/build/repos/host/かmruby/build/repos/test/にクローンします。エントリーの無いgemに使う--depth 1は付けません。そして、記録したコミットをチェックアウトします。HEADはdetachedになります。ビルドの最後に、rakeは使ったクローンからロックを書き直します。デフォルトのgemの一覧では内容が変わらないので、ビルドの後もgit statusはきれいなままです。

rakeは、mruby/build/repos/の下にgemのディレクトリが無いときだけ、gemをクローンします。既にあるクローンは、fetchせずにロックのコミットでチェックアウトするので、そのコミットがクローンの中に無ければなりません。ロックを変えたときは、ビルドの前にmruby/buildを消してください。build_config.rb.lockをまだコミットしていなかった頃の、ロックの無いビルドが残したクローンには、そのときブランチの先頭だったコミットしかありません。

gemを別のコミットに移すには、次のようにします。

1. build_config.rb.lockで、gemのエントリーがある各セクションのcommit:を変えます。ブランチの現在の先頭を取るなら、エントリーを消します。
2. rm -rf mruby/buildでクローンを消します。このコマンドはbuild_config.rb.lockを残します。ここではmake clean_mrubyは使えません。make clean_mrubyは何かを消す前にrakeを実行し、rakeはbuild_config.rbを読むときに既にある各クローンをロックのコミットでチェックアウトします。そのため、クローンにそのコミットが無いと、fatal: reference is not a treeで止まります。
3. sh test.shかsh build.shで、ビルドします。
4. rakeが書いたbuild_config.rb.lockをコミットします。

build_config.rbにgemを加えると、次のビルドはそのブランチの先頭をクローンし、そのgemと、それが依存するgemのエントリーをロックに加えます。変更と一緒にロックをコミットしてください。gemを消してもrakeはそのエントリーを残します。rakeは読んだエントリーをすべて書き戻すからです。そのためエントリーは自分でロックから消してください。同梱のmrubyを更新した後は、mruby/buildを消してビルドし、更新と一緒にロックをコミットしてください。rakeは新しいバージョンを記録します。新しいmrubyが自分のgemとして持つようになった依存先はクローンしなくなるので、そのエントリーを消してください。

ビルドが取ってくるもののうち、ロックが固定しないものが2つあります。

• mruby/mgem-list。mrubyは、mgem:で宣言したgemのリポジトリや、ソースを指定せずに宣言した依存先のうちmruby自身のgemでないもののリポジトリを探すために、このgemの一覧の先頭をクローンします。デフォルトのgemの一覧には、mruby/mgem-listは必要ありません。mruby 4.0.0に更新する前までは、testのビルドに要りました。matsumotory/mruby-simplehttpは、NO_SSLを設定しない限り、ソースを指定せずにmruby-polarsslに依存し、その一覧がリポジトリのluisbebop/mruby-polarsslを返していました。そのgemはmruby 3.4で削除されたmruby-printに依存するので、今はbuild_config.rbがtestのビルドにNO_SSLを設定しています。テストのクライアントのSimpleHttpはHTTPSを使えず、テストスイートはHTTPSのリクエストをcurlとopenssl s_clientで送ります。加えたgemにこの一覧が要る場合、ロックはgemのコミットを固定しますが、URLは一覧が決めます。一覧が別のURLを返すようになると、ロックにはそのエントリーが無いので、rakeはそのリポジトリの先頭をクローンします。そのため、build_config.rbはサードパーティのgemをgithub:で宣言します。
• symisc/vedis。matsumotory/mruby-vedisのmrbgem.rakeは、gemのビルドのディレクトリのmruby/build/host/mrbgems/mruby-vedis/vedisが無いとき、git cloneでvedisをそこにクローンします。このときクローンするのは、デフォルトのブランチの先頭です。

コミットを指定したクローンはリポジトリの履歴をすべて持つので、最初のビルドは、ロックの無いビルドより多くのデータを取ってきます。デフォルトのビルドは19個のクローンを作ります。mruby/build/repos/hostに12個、mruby/build/repos/testに7個です。2026年10月4日に、空のmruby/buildからビルドした後に測ると、クローンは約9.3 MiBで、内訳は7.7 MiBと1.7 MiBでした。mruby 4.0.0に更新する前は、testのビルドがluisbebop/mruby-polarsslとそのサブモジュールのARMmbed/mbedtlsもクローンしていました。当時デフォルトのビルドのクローンが使っていた約178 MiBの大部分は、これらでした。

3. バイナリをビルドする

3-A. build.shを使う

リポジトリのルートで、手順の対象となるnginxのソースを明示してビルドします。

NGINX_SOURCE_DIR="$(mktemp -d)/nginx"
git clone --depth 1 --branch release-1.31.8 https://github.com/nginx/nginx "$NGINX_SOURCE_DIR"
NGINX_SRC_ENV="$NGINX_SOURCE_DIR" sh ./build.sh
make install
./build/nginx/sbin/nginx -V

build.shの担当は設定とコンパイルです。インストールには、別途make installを実行してください。

デフォルトのprefixは$PWD/build/nginxです。ビルドするユーザーが書き込めれば、sudoは必要ありません。

上流のgit checkoutを指定すると、nginx.orgのtarball取得に依存せずビルドできます。NGINX_SRC_ENVを省略すると、checkout内のnginx_versionを使います。この開発版の設定は1.31.8です。他の版を選ぶ場合は、nginx -Vと上流の変更を確認してください。

NGINX_SRC_ENVは既存のnginxソースを選びます。インストールまで終わる前に、そのツリーを消さないでください。

並列コンパイルはNUM_THREADS_ENV=4で4個に制限できます。

インストール先を変える場合は絶対パスを指定します。NGINX_CONFIG_OPT_ENVはデフォルトのnginxオプションを置き換えるため、必要なものをすべて列挙してください。

NGINX_SRC_ENV="$NGINX_SOURCE_DIR" NGINX_CONFIG_OPT_ENV="--prefix=$PWD/build/custom-nginx --with-stream --with-http_stub_status_module --with-cc-opt=-fno-common" sh ./build.sh
make install

3-B. Makefileを使う

既存のnginxソースには、configureとmakeでも同じ設定を指定できます。NGINX_SOURCE_DIRはnginxソースの絶対パスであり、インストール先のprefixではありません。

./configure --with-ngx-src-root="$NGINX_SOURCE_DIR" --with-ngx-config-opt="--prefix=$PWD/build/nginx --with-stream --with-cc-opt=-fno-common"
make
make install

現在のオプションは./configure --helpで確認できます。--with-build-dir、--with-mruby-root、--with-ndk-root、--with-openssl-src、--with-openssl-optなどがあります。

--with-mruby-incdirを指定する場合は、mrubyのbuild/host/includeも含めてください。デフォルトは<mruby_root>/src <mruby_root>/include <mruby_root>/build/host/includeです。ngx_mrubyが使う<mruby/presym.h>は、この場所に生成されるヘッダを読み込みます。

3-C. nginx側からビルド

既存のnginxビルドへ加えるには、まずmrubyをビルドしてリンク設定を生成します。その後、nginxのconfigureにngx_mrubyと同梱NDKの両方を加えます。他に必要なnginxオプションも維持してください。

NGX_MRUBY_SOURCE_DIR="$PWD"
./configure --with-ngx-src-root="$NGINX_SOURCE_DIR"
make build_mruby
make generate_gems_config
cd "$NGINX_SOURCE_DIR"
# A git checkout uses auto/configure; a release tarball uses ./configure.
if [ -f auto/configure ]; then NGX_CONFIGURE=./auto/configure; else NGX_CONFIGURE=./configure; fi
"$NGX_CONFIGURE" --prefix="$NGX_MRUBY_SOURCE_DIR/build/nginx" --add-module="$NGX_MRUBY_SOURCE_DIR" --add-module="$NGX_MRUBY_SOURCE_DIR/dependence/ngx_devel_kit" --with-stream
make
make install

ビルドのオプション

streamモジュールを有効にする

build.shのデフォルトはstream有効です。独自のnginxオプションには--with-streamを含めます。TCP/UDPの検証方法はstreamディレクティブとテスト手順にあります。

自前のOpenSSLでビルドする

通常はシステムのOpenSSL開発パッケージを使います。

独自の版を使う場合は、ソースを展開して版を記録し、その絶対パスを指定してください。

NGINX_SRC_ENV="$NGINX_SOURCE_DIR" sh ./build.sh --with-openssl-src=/absolute/path/to/openssl-source
make install

過去のOpenSSL 1.0.2g取得例を、現在の推奨手順として使わないでください。独自のOpenSSLビルドには別途検証が必要です。

動的モジュールとしてビルドする

ビルド方式を変えるときは、新しいcheckoutを使います。静的ビルドのnginx設定を再利用しないためです。そのシェルで、3-Aと同じrelease-1.31.8の新しいソースツリーをNGINX_SOURCE_DIRへ設定してください。

NGINX_SRC_ENV="$NGINX_SOURCE_DIR" BUILD_DYNAMIC_MODULE=TRUE sh ./build.sh
make install
./build_dynamic/nginx/sbin/nginx -V

デフォルトのprefixは$PWD/build_dynamic/nginxです。eventsとhttpより前のmainコンテキストで、そのインストール先のモジュールを読み込みます。

load_module /absolute/path/to/ngx_mruby/build_dynamic/nginx/modules/ngx_http_mruby_module.so;

このモジュールと一緒にビルドしたnginxを使い、起動前にnginx -tで確認します。下の試用例を動的ビルドで使うときは、NGX_BINをそのバイナリへ変更し、設定に絶対パスのload_module行を加えてください。

独自のビルドでは、設定と生成先を次のように揃えます。

• ngx_mrubyのconfigure：--enable-dynamic-module
• gem設定の生成：make generate_gems_config_dynamic
• nginxへのngx_mruby追加：--add-dynamic-module
• 同梱NDKの追加：--add-module

auto-sslのmrbgemと、それと一緒に入っていたクラス

ngx_mruby 3.0.0には、auto-sslのmrbgemがありません。このgemはmrbgems/auto-sslにあり、Nginx::SSL::ACMEのクラスを定義していました。mrubyのビルドは、NGX_MRUBY_AUTO_SSLをもう読みません。詳しくはauto-sslのmrbgemとNGX_MRUBY_AUTO_SSLが無くなるにあります。このgemのNginx::SSL::ACME::ClientはACMEv1のnew-reg、new-authz、new-certを使いますが、Let’s EncryptはACMEv1のサービスを終えています。このgemがTLSのために必要とするpyama86/mruby-polarsslは、2017-03-03からコミットが無く、mruby 4ではビルドできません。mruby/ext/io.hをインクルードしますが、mruby 4.0はこのヘッダをmruby/io.hに改名しました。ACMEのサーバーから証明書を取得するには、nginx自身のモジュールであるngx_http_acme_module、つまりnginx-acmeを使ってください。Nginx::SSL::ACMEが必要なサーバーは、2.xのビルドを使い続けてください。詳細は2.xのドキュメントを参照。

ngx_mruby 2.xは、auto-sslが依存するgemもビルドしていました。pyama86/mruby-acme-client、GPLでライセンスされたpyama86/mruby-polarssl、matsumotory/mruby-httprequest、matsumotory/mruby-simplehttp、mattn/mruby-http、mattn/mruby-base64、takahashim/mruby-forwardable、iij/mruby-tempfileです。デフォルトのビルドのほかのgemはこれらを必要としないので、3.0.0のデフォルトのビルドには、これらが定義するものもありません。

• クラスとモジュールのAcme、CustomHttpRequest、OpenSSL、PolarSSL、HttpRequest、SimpleHttp、HTTP、Base64、Forwardable、FORWARDABLE、Tempfile、TempfilePath
• iij/mruby-tempfileがDirに加えるDir.tmpdirとDir.mktmpdir、それらの補助のDir._tmpname。Dirのクラス自体は、デフォルトのビルドに残ります。

Dir.tmpdirの代わりには、ENV['TMPDIR'] || '/tmp'を使ってください。mruby-tempfileのDir.tmpdirは、/tmpに戻る前にTMP、TEMP、USERPROFILEも読んでいました。Dir.mktmpdirの代わりには、ほかのプロセスが使わない名前でDir.mkdir(path, 0700)でディレクトリを作ってください。名前が既に使われているとDir.mkdirはErrno::EEXISTを起こします。ブロック付きのDir.mktmpdirは、ブロックが戻るとディレクトリと中身をすべて消していました。その場合は自分で消してください。Dir.entriesで各ディレクトリの中身を一覧にし、File.directory?でファイルとディレクトリを見分けます。どちらもデフォルトのビルドにあります。ファイルはFile.deleteで、ディレクトリはDir.rmdirで、深いものから先に消します。中身の残るディレクトリにDir.rmdirを使うと、Errno::ENOTEMPTYが起きます。Base64の代わりには、デフォルトのビルドでも使えるコアのpack('m0')とunpack1('m')を使ってください。

tmpdir = ENV['TMPDIR'] || '/tmp'                              # Dir.tmpdir
path = "#{tmpdir}/myapp-#{Process.pid}-#{SecureRandom.hex(8)}"
Dir.mkdir(path, 0700)                                         # Dir.mktmpdir('myapp-')

ほかの定数が要るなら、それを定義するgemを、自分のbuild_config.rbにconf.gemの行で加えてください。pyama86/mruby-polarsslに依存するgemは、mruby 4ではビルドが通りません。

4. ngx_mrubyをインストールする

コンパイル後にmake installを実行すると、設定済みのprefixへ配置されます。

この手順のprefixはbuild/nginxです。常に/usr/local/nginxへ入るわけではありません。

既存の本番prefixを更新する場合は、権限と更新計画を確認してください。以下の試用例は独立した実行先を使います。

5. Rubyのスクリプトを動かす

実行先とログには一時ディレクトリを使います。

• 待受先：127.0.0.1:18088
• 停止対象：例で起動したnginx

18088が使用中なら、例のポートを別の未使用番号に統一してください。

インストール後、リポジトリのルートで実行してください。以下は一つのシェルで続けて使うコマンドです。

(
set -eu
NGX_BIN="$PWD/build/nginx/sbin/nginx"
RUN_DIR="$(mktemp -d)"
mkdir -p "$RUN_DIR/logs"
printf 'Trial runtime: %s\n' "$RUN_DIR"
started=0
cleanup() {
    if [ "$started" = 1 ]; then "$NGX_BIN" -p "$RUN_DIR/" -c nginx.conf -s quit; fi
}
trap cleanup EXIT
cat > "$RUN_DIR/hello.rb" <<'RUBY'
Nginx::Headers_out.new["Content-Type"] = "text/plain"
Nginx.rputs "hello ngx_mruby\n"
RUBY
cat > "$RUN_DIR/nginx.conf" <<CONF
worker_processes 1;
pid logs/nginx.pid;
error_log logs/error.log notice;
events { worker_connections 64; }
http {
    access_log off;
    default_type text/plain;
    server {
        listen 127.0.0.1:18088;
        location = /inline {
            mruby_content_handler_code 'Nginx::Headers_out.new["Content-Type"] = "text/plain"; Nginx.rputs "hello ngx_mruby\\n"';
        }
        location = /script {
            mruby_content_handler "$RUN_DIR/hello.rb" cache;
        }
    }
}
CONF
"$NGX_BIN" -p "$RUN_DIR/" -c nginx.conf -t
"$NGX_BIN" -p "$RUN_DIR/" -c nginx.conf
started=1
curl --fail --show-error --silent --include http://127.0.0.1:18088/inline
curl --fail --show-error --silent --include http://127.0.0.1:18088/script
"$NGX_BIN" -p "$RUN_DIR/" -c nginx.conf -t && "$NGX_BIN" -p "$RUN_DIR/" -c nginx.conf -s reload
"$NGX_BIN" -p "$RUN_DIR/" -c nginx.conf -s quit
started=0
)

両URLの期待値：

• ステータス：200
• ヘッダ：Content-Type: text/plain
• 本文：hello ngx_mruby＋改行

Date・Serverは環境依存です。

例はcontentフェーズで動き、リクエストをまたぐRuby状態を使いません。reloadはmasterプロセスを残してworkerを入れ替えます。graceful quitは、この実行用ディレクトリのPIDファイルを使います。

5-A. スクリプトファイル

mruby_content_handlerはスクリプトのパスを取ります。例ではnginxの作業ディレクトリに依存しない絶対パスを指定します。

5-B. インラインコード

mruby_content_handler_codeには、nginx設定内のRubyコードを渡します。

heredocの引用は、nginxとshellの両方を考慮してください。

5-C. スクリプトハンドラ

別のインターフェースとしてmruby_add_handler onもあります。ディレクティブリファレンスを参照してください。試用例は明示的なlocationを使い、すべての一致する.rbファイルの実行を有効にしません。

スクリプトのcacheはコンパイル結果をキャッシュします。省略すると、mruby_cache onが適用される場合を除き、リクエストごとに読み込みとコンパイルを行います。本番用のキャッシュを選ぶ前に、リファレンスで動作を確認してください。

6. nginxを起動する

検証・起動・reload・quitには、インストールしたバイナリと同じ-p・-cを使います。システムの別のnginxへ置き換えないでください。そのバイナリにはngx_mrubyが入っていない場合があります。

7. 動作を確認する

失敗したときは、設定を変える前に次を確認してください。

症状	確認すること
バイナリがない	build.shはコンパイルまでです。make installと設定済みprefixを確認します。
unknown directive	ビルドしたnginxを使います。動的ビルドはmainのload_moduleと対応バイナリを確認します。
ビルドエラー	開発用パッケージと、ビルドログの最初のエラーを確認する。
取得エラー	対象タグのnginxを取得し、NGINX_SRC_ENVで指定。
bind()に失敗	未使用ポートを選ぶ。他者のプロセスは停止しない。
Ruby実行エラー	$RUN_DIR/logs/error.logを参照。絶対パス・権限・コードを確認。
本文の不一致	nginx -t、URL・ポート・ログを確認。接続成功だけでは不十分です。

2026年10月29日、ngx_mruby開発版のコミット6d65a12ecf166e11a6ece40d56f0f2efb05ea112とnginx 1.31.8で検証しました。nginxはrelease-1.31.8をNGINX_SRC_ENVで指定し、Ubuntu 22.04 aarch64、GCC 11.4.0、Ruby 3.0.2/rake 13.0.6を使用しています。

静的ビルドは並列数4とmake installで成功しました。第5節をそのまま抽出して実行し、両応答の200・text/plain・16バイト本文と、設定検証・reload・quitを確認しました。gem lockの変更はありません。

検証結果は、記録したコミットに対するものです。将来のnext全体への保証ではありません。

独自prefix・nginx直接ビルド・動的モジュール・独自OpenSSLは、設定方法の説明です。この実行の検証対象には含めていません。

完全な統合テスト、sanitizer、対象nginxの版はテスト手順を参照してください。この試用は小さなHTTP例の確認です。独自モジュール・TLS・stream・性能・本番展開の検証ではありません。

Dockerの参考例

別リポジトリのdocker-ngx_mrubyは過去の例です。ここで検証した版固定のインストールには含まれません。利用する場合は、イメージ・設定・依存を別途確認してください。

このソースビルドに、レジストリのアカウントは不要です。