Apache Settings in the Boxfile

Last Updated October 2014

The Boxfile is a yaml config file that allows you to custom-configure your app's environment. The following httpd configuration options are available in the Boxfile and allow you to tailor-fit your Apache build specific to your needs. After reading this doc, you should understand how to:

  • How to customize your Apache configuration
  • Bask in the awesomeness of Apache and Pagoda Box

Overview of Apache Boxfile Settings YAML

  web1:
    httpd_document_root: public
    httpd_index_list:
      - index.html
    httpd_version: 2.2.23
    httpd_php_interpreter: fastcgi
    httpd_modules:
      - include
      - env
      - mime_magic
      - rewrite
    httpd_log_level: warn
    httpd_timeout: 30
    httpd_server_limit: 128
    httpd_max_clients: 128
    httpd_static_expire: 86400
    httpd_server_admin: 'email@domain.com'
    httpd_xsendfilepaths:
      - /var/www/public/files
      - /var/www/other
/Boxfile

Apache Configuration Settings

Document Root

Your httpd_document_root is root of your executable app source. For instance, if you like to house your app in /public for security or organizational purposes, you can specify that here. The default is the root of your project.

httpd_document_root YAML

  web1:
    httpd_document_root: public
/Boxfile
Index List

When a path is not specified in the url, these files will be served in order in which they're listed.

httpd_index_list YAML

  # default setting
  web1:
    httpd_index_list:
      - index.html
      - index.php
/Boxfile
Apache Version

Specify what version of Apache you would like to use. Currently, 2.2.23 is the only available option.

httpd_version YAML

  # default setting
  web1:
    httpd_version: 2.2.23
/Boxfile
Apache PHP Interpreter

Specify which PHP interepreter you would like Apache to use.

  • fastcgi (Default)

  • mod_php

httpd_php_interpreter YAML

  # default setting
  web1:
    httpd_php_interpreter: fastcgi
/Boxfile
Apache Modules

This setting allows you specify what Apache modules you would like enabled or disabled. View the full list of available Apache Modules. By default, all modules are enabled.

httpd_modules YAML

  web1:
    httpd_modules:
      - include
      - env
      - mime_magic
      - rewrite
      - fastcgi
/Boxfile

Listing a Single Module Will Disable All Others

By default, all available Apache modules are enabled. Listing a single module will override the default and all unlisted modules will no longer be enabled. Be aware there are dependencies between Apache Modules not managed by Pagoda Box.

Apache Log Level

Sets the minimum importance for a message to be logged (the "level" of the message). See LogLevel Apache Docs for available levels.

httpd_log_level YAML

  # default setting
  web1:
    httpd_log_level: warn
/Boxfile
Apache Timeout

This will set the number of seconds apache will wait before timing out.

httpd_timeout YAML

  # default setting
  web1:
    httpd_timeout: 30
/Boxfile
Apache ServerLimit

This sets the maximum configured value for MaxClients for the lifetime of the Apache process.

Note: This configuration must be greater than or equal to the Apache MaxClients.

Use the ServerLimit Setting Carefully

Changing the Apache ServerLimit can drastically affect how your web instances use available resources and can lead to reduced performance and/or unresponsiveness.

httpd_server_limit YAML

  # default setting
  web1:
    httpd_server_limit: 128
/Boxfile
Apache MaxClients

This will set the maximum number of connections that will be processed simultaneously.

Note: This configuration must be less than or equal to the Apache ServerLimit.

Use the MaxClients Setting Carefully

Changing the Apache MaxClients can drastically affect how your web instances use available resources and can lead to reduced performance and/or unresponsiveness.

httpd_max_clients YAML

  # default setting
  web1:
    httpd_max_clients: 128
/Boxfile
Apache Static Expire

This will add far future expires to your header and set the number of seconds static assets are cached. By default, static asset caching is not enabled. We only recommend using this directive on apps whose static assets do not change often.

httpd_static_expire YAML

  web1:
    httpd_static_expire: 86400
/Boxfile
Server Admin

This allows you to specify server admin contact information if your web process becomes unresponsive but Apache is still running.

httpd_server_admin YAML

  # default setting
  web1:
    httpd_server_admin: 'support@pagodabox.com'
/Boxfile
XSendFilePath

All files within these paths are allowed to get served through mod_xsendfile.

httpd_xsendfilepaths YAML

  web1:
    httpd_xsendfilepaths:
      - /var/www/public/files
      - /var/www/other
/Boxfile

If you have any questions, suggestions, or corrections, let us know.