Configuration

By including a configuration file in the root of your application repository, you can go all the way.

For Nginx it’s an nginx.conf and for Apache2 it’s a httpd.conf. Make sure either configuration file configures the entire server (not just a single virtual host).

Options

The following are the most common configuration options you will need:

variable	description
`BP_WEB_SERVER_ENABLE_PUSH_STATE`	enable push state/history, for single page apps
`BP_WEB_SERVER_ROOT`	set the document root
`BP_NGINX_VERSION`	set Nginx version
`BP_HTTPD_VERSION`	set Apache version

You can set any of the variables with runway app config set or a project.toml file.

Live reloading

The Paketo buildpacks also support a “live reload” mechanism, which is not supported on Runway.

Nginx

To configure Nginx to use the user’s actual IP address, the following snippet will give you an idea for what is expected:

worker_processes 1;
daemon off;

error_log stderr;

events {
  worker_connections 1024;
}

http {
  charset utf-8;
  access_log /dev/stdout;
  default_type application/octet-stream;
  include mime.types;
  sendfile on;

  tcp_nopush on;
  keepalive_timeout 30;
  # Ensure that redirects don't include the internal container PORT - 8080
  port_in_redirect off;

  set_real_ip_from 10.244.0.0/16;
  real_ip_header X-Forwarded-For;

  server {
    port_in_redirect off;
    absolute_redirect off;

    listen {{port}};
    # snip
  }
}

Along with the nginx.conf, you will also need to add a mime.types file and the complete server block. For a complete example configuration, see how to deploy an Angular app).

Otherwise, anything that Nginx supports will work on Runway.

Setting the port

We suggest to add the listen {{port}}; directive, to avoid hard-coding this setting. This allows runway app config set PORT=1234 to work, so you don’t need to update the setting in the configuration file.

Redirects

To avoid side-effects in redirects where Nginx adds the container port to a URL, it’s necessary to set port_in_redirect off; and absolute_redirect off; if you supply a custom configuration file. The buildpack will take care of this for you.

Partial

Apache2 generally supports loading dynamic configuration through .htaccess files. The trade off is performance and this is why Nginx does not support that out of the box.

However, the Nginx buildpack supports a work-around so you can set a partial in the web server’s configuration. This partial is included in the generated configuration’s server {} block.

So for example, if you’d like to redirect traffic to /api to another application (app-api) on Runway — this is how!

First set BP_WEB_SERVER_INCLUDE_FILE_PATH:

Runway CLI

runway app config set BP_WEB_SERVER_INCLUDE_FILE_PATH=proxy.conf

project.toml

[build]
  [[build.env]]
    name = "BP_WEB_SERVER_INCLUDE_FILE_PATH"
    value = "proxy.conf"

And add the following proxy.conf file into your repository:

proxy.conf

location /api/ {
    proxy_pass http://app-api.app-api.cluster.local:5000/api/;
}

After you deployed your application, the configuration from proxy.conf will be included in the generated nginx.conf that is used to serve your application.

Company