Custom Nginx Configs with the Nanobox PHP Engine

Setting up a PHP environment can be a tedious process, but Nanobox's PHP engine makes it really easy. The PHP engine automatically builds and prepares your environment, during which it will generate configuration files based on settings defined in your defined in your boxfile.yml. When using nginx as your webserver, it will auto-generate an nginx.conf which is used by the engine's php-server helper script (a really simple way to start your app). It's possible to add custom Nginx options such as rewrites, redirects, file-type restrictions, etc., but it requires a little setup.

Specify Nginx Settings in Your boxfile.yml

The PHP engine exposes three Nginx settings in the boxfile.yml that detemine the contents of the auto-generated nginx.conf: document_root, nginx_index_list, and nginx_default_gateway. Update these settings to match the needs of your app. If these defaults work for you, you don't need to include them in your boxfile.yml.

run.config:
  engine: php
  engine.config:
    document_root: /
    nginx_index_list:
      - index.php
      - index.html
    nginx_default_gateway: index.php

Copy & Customize the Generated nginx.conf

Nanobox generates the nginx.conf as part of your app's build process. To trigger a build, generate the nginx.conf, and drop into a Nanobox console, run the following from the root of your project:

nanobox run

From inside the Nanobox console, copy the generated nginx.conf to a custom location inside your project. For this tutorial, just copy it to the root of your project.

cp /data/etc/nginx/nginx.conf nginx.conf

Add any custom configuration options to the duplicate nginx.conf in your project root.

Using the Custom nginx.conf

The PHP engine provides a handy helper script for starting your app - php-server. Without it, you'd have to start Nginx and PHP-FPM individually, which when working locally, can get messy. php-server starts everything for you with a single command, but it assumes the nginx.conf is located at /data/etc/nginx/nginx.conf.

To use your custom nginx.conf and still enjoy the convenience of the php-server script, replace the auto-generated nginx.conf with your custom nginx.conf in your app's build process. This can be done using extra_steps in your run.config. You should also set your custom nginx.conf as a build_trigger so if you make changes, Nanobox will detect them and re-run the build process to copy those changes into place.

run.config:
  engine: php
  extra_steps:
    - cp nginx.conf /data/etc/nginx/nginx.conf
  build_triggers:
    - nginx.conf

Rebuild & Start the App

With everything in place, your boxfile.yml should look something like this:

run.config:
  engine: php
  engine.config:
    document_root: /
    nginx_index_list:
      - index.php
      - index.html
    nginx_default_gateway: index.php
  extra_steps:
    - cp nginx.conf /data/etc/nginx/nginx.conf
  build_triggers:
    - nginx.conf

To rebuild the code, copy your custom nginx.conf into place, and start your app, run the following from the root of your project:

nanobox run php-server

That's it! You can now access your app running with your custom nginx.conf from your browser.

Posted in PHP, Nginx