3rdparty/modules/apache/README.passenger.md

   1 # Passenger
   2
   3 Just enabling the Passenger module is insufficient for the use of Passenger in
   4 production. Passenger should be tunable to better fit the environment in which
   5 it is run while being aware of the resources it required.
   6
   7 To this end the Apache passenger module has been modified to apply system wide
   8 Passenger tuning declarations to `passenger.conf`. Declarations specific to a
   9 virtual host should be passed through when defining a `vhost` (e.g.
  10 `rack_base_uris` parameter on the `apache::vhost` type, check `README.md`).
  11
  12 Also, general apache module loading parameters can be supplied to enable using
  13 a customized passenger module in place of a default-package-based version of
  14 the module.
  15
  16 # Operating system support and Passenger versions
  17
  18 The most important configuration directive for the Apache Passenger module is
  19 `PassengerRoot`. Its value depends on the Passenger version used (2.x, 3.x or
  20 4.x) and on the operating system package from which the Apache Passenger module
  21 is installed.
  22
  23 The following table summarises the current *default versions* and
  24 `PassengerRoot` settings for the operating systems supported by
  25 puppetlabs-apache:
  26
  27 OS               | Passenger version  | `PassengerRoot`
  28 ---------------- | ------------------ | ----------------
  29 Debian 7         | 3.0.13             | /usr
  30 Debian 8         | 4.0.53             | /usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini
  31 Ubuntu 12.04     | 2.2.11             | /usr
  32 Ubuntu 14.04     | 4.0.37             | /usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini
  33 RHEL with EPEL6  | 3.0.21             | /usr/lib/ruby/gems/1.8/gems/passenger-3.0.21
  34
  35 As mentioned in `README.md` there are no compatible packages available for
  36 RHEL/CentOS 5 or RHEL/CentOS 7.
  37
  38 ## Configuration files and locations on RHEL/CentOS
  39
  40 Notice two important points:
  41
  42 1. The Passenger version packaged in the EPEL repositories may change over time.
  43 2. The value of `PassengerRoot` depends on the Passenger version installed.
  44
  45 To prevent the puppetlabs-apache module from having to keep up with these
  46 package versions the Passenger configuration files installed by the
  47 packages are left untouched by this module. All configuration is placed in an
  48 extra configuration file managed by puppetlabs-apache.
  49
  50 This means '/etc/httpd/conf.d/passenger.conf' is installed by the
  51 `mod_passenger` package and contains correct values for `PassengerRoot` and
  52 `PassengerRuby`. Puppet will ignore this file. Additional configuration
  53 directives as described in the remainder of this document are placed in
  54 '/etc/httpd/conf.d/passenger_extra.conf', managed by Puppet.
  55
  56 This pertains *only* to RHEL/CentOS, *not* Debian and Ubuntu.
  57
  58 ## Third-party and custom Passenger packages and versions
  59
  60 The Passenger version distributed by the default OS packages may be too old to
  61 be useful. Newer versions may be installed via Gems, from source or from
  62 third-party OS packages.
  63
  64 Most notably the Passenger developers officially provide Debian packages for a
  65 variety of Debian and Ubuntu releases in the [Passenger APT
  66 repository](https://oss-binaries.phusionpassenger.com/apt/passenger). Read more
  67 about [installing these packages in the offical user
  68 guide](http://www.modrails.com/documentation/Users%20guide%20Apache.html#install_on_debian_ubuntu).
  69
  70 If you install custom Passenger packages and newer version make sure to set the
  71 directives `PassengerRoot`, `PassengerRuby` and/or `PassengerDefaultRuby`
  72 correctly, or Passenger and Apache will fail to function properly.
  73
  74 For Passenger 4.x packages on Debian and Ubuntu the `PassengerRoot` directive
  75 should almost universally be set to
  76 `/usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini`.
  77
  78 # Parameters for `apache::mod::passenger`
  79
  80 The following class parameters configure Passenger in a global, server-wide
  81 context.
  82
  83 Example:
  84
  85 ```puppet
  86 class { 'apache::mod::passenger':
  87   passenger_root             => '/usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini',
  88   passenger_default_ruby     => '/usr/bin/ruby1.9.3',
  89   passenger_high_performance => 'on',
  90   rails_autodetect           => 'off',
  91   mod_lib_path               => '/usr/lib/apache2/custom_modules',
  92 }
  93 ```
  94
  95 The general form is using the all lower-case version of the configuration
  96 directive, with underscores instead of CamelCase.
  97
  98 ## Parameters used with passenger.conf
  99
 100 If you pass a default value to `apache::mod::passenger` it will be ignored and
 101 not passed through to the configuration file.
 102
 103 ### passenger_root
 104
 105 The location to the Phusion Passenger root directory. This configuration option
 106 is essential to Phusion Passenger, and allows Phusion Passenger to locate its
 107 own data files.
 108
 109 The default depends on the Passenger version and the means of installation. See
 110 the above section on operating system support, versions and packages for more
 111 information.
 112
 113 http://www.modrails.com/documentation/Users%20guide%20Apache.html#_passengerroot_lt_directory_gt
 114
 115 ### passenger_default_ruby
 116
 117 This option specifies the default Ruby interpreter to use for web apps as well
 118 as for all sorts of internal Phusion Passenger helper scripts, e.g. the one
 119 used by PassengerPreStart.
 120
 121 This directive was introduced in Passenger 4.0.0 and will not work in versions
 122 < 4.x. Do not set this parameter if your Passenger version is older than 4.0.0.
 123
 124 Defaults to `undef` for all operating systems except Ubuntu 14.04, where it is
 125 set to '/usr/bin/ruby'.
 126
 127 http://www.modrails.com/documentation/Users%20guide%20Apache.html#PassengerDefaultRuby
 128
 129 ### passenger_ruby
 130
 131 This directive is the same as `passenger_default_ruby` for Passenger versions
 132 < 4.x and must be used instead of `passenger_default_ruby` for such versions.
 133
 134 It makes no sense to set `PassengerRuby` for Passenger >= 4.x. That
 135 directive should only be used to override the value of `PassengerDefaultRuby`
 136 on a non-global context, i.e. in `<VirtualHost>`, `<Directory>`, `<Location>`
 137 and so on.
 138
 139 Defaults to `/usr/bin/ruby` for all supported operating systems except Ubuntu
 140 14.04, where it is set to `undef`.
 141
 142 http://www.modrails.com/documentation/Users%20guide%20Apache.html#PassengerRuby
 143
 144 ### passenger_high_performance
 145
 146 Default is `off`. When turned `on` Passenger runs in a higher performance mode
 147 that can be less compatible with other Apache modules.
 148
 149 http://www.modrails.com/documentation/Users%20guide%20Apache.html#PassengerHighPerformance
 150
 151 ### passenger_max_pool_size
 152
 153 Sets the maximum number of Passenger application processes that may
 154 simultaneously run. The default value is 6.
 155
 156 http://www.modrails.com/documentation/Users%20guide%20Apache.html#_passengermaxpoolsize_lt_integer_gt
 157
 158 ### passenger_pool_idle_time
 159
 160 The maximum number of seconds a Passenger Application process will be allowed
 161 to remain idle before being shut down. The default value is 300.
 162
 163 http://www.modrails.com/documentation/Users%20guide%20Apache.html#PassengerPoolIdleTime
 164
 165 ### passenger_max_requests
 166
 167 The maximum number of request a Passenger application will process before being
 168 restarted. The default value is 0, which indicates that a process will only
 169 shut down if the Pool Idle Time (see above) expires.
 170
 171 http://www.modrails.com/documentation/Users%20guide%20Apache.html#PassengerMaxRequests
 172
 173 ### passenger_stat_throttle_rate
 174
 175 Sets how often Passenger performs file system checks, at most once every _x_
 176 seconds. Default is 0, which means the checks are performed with every request.
 177
 178 http://www.modrails.com/documentation/Users%20guide%20Apache.html#_passengerstatthrottlerate_lt_integer_gt
 179
 180 ### rack_autodetect
 181
 182 Should Passenger automatically detect if the document root of a virtual host is
 183 a Rack application. Not set by default (`undef`). Note that this directive has
 184 been removed in Passenger 4.0.0 and `PassengerEnabled` should be used instead.
 185 Use this directive only on Passenger < 4.x.
 186
 187 http://www.modrails.com/documentation/Users%20guide%20Apache.html#_rackautodetect_lt_on_off_gt
 188
 189 ### rails_autodetect
 190
 191 Should Passenger automatically detect if the document root of a virtual host is
 192 a Rails application.  Not set by default (`undef`). Note that this directive
 193 has been removed in Passenger 4.0.0 and `PassengerEnabled` should be used
 194 instead. Use this directive only on Passenger < 4.x.
 195
 196 http://www.modrails.com/documentation/Users%20guide%20Apache.html#_railsautodetect_lt_on_off_gt
 197
 198 ### passenger_use_global_queue
 199
 200 Allows toggling of PassengerUseGlobalQueue.  NOTE: PassengerUseGlobalQueue is
 201 the default in Passenger 4.x and the versions >= 4.x have disabled this
 202 configuration option altogether.  Use with caution.
 203
 204 ### passenger_app_env
 205
 206 Sets the global default `PassengerAppEnv` for Passenger applications. Not set by
 207 default (`undef`) and thus defaults to Passenger's built-in value of 'production'.
 208 This directive can be overridden in an `apache::vhost` resource.
 209
 210 https://www.phusionpassenger.com/documentation/Users%20guide%20Apache.html#PassengerAppEnv
 211
 212 ## Parameters used to load the module
 213
 214 Unlike the tuning parameters specified above, the following parameters are only
 215 used when loading customized passenger modules.
 216
 217 ### mod_package
 218
 219 Allows overriding the default package name used for the passenger module
 220 package.
 221
 222 ### mod_package_ensure
 223
 224 Allows overriding the package installation setting used by puppet when
 225 installing the passenger module. The default is 'present'.
 226
 227 ### mod_id
 228
 229 Allows overriding the value used by apache to identify the passenger module.
 230 The default is 'passenger_module'.
 231
 232 ### mod_lib_path
 233
 234 Allows overriding the directory path used by apache when loading the passenger
 235 module. The default is the value of `$apache::params::lib_path`.
 236
 237 ### mod_lib
 238
 239 Allows overriding the library file name used by apache when loading the
 240 passenger module. The default is 'mod_passenger.so'.
 241
 242 ### mod_path
 243
 244 Allows overriding the full path to the library file used by apache when loading
 245 the passenger module. The default is the concatenation of the `mod_lib_path`
 246 and `mod_lib` parameters.
 247
 248 # Dependencies
 249
 250 RedHat-based systems will need to configure additional package repositories in
 251 order to install Passenger, specifically:
 252
 253 * [Extra Packages for Enterprise Linux](https://fedoraproject.org/wiki/EPEL)
 254 * [Phusion Passenger](http://passenger.stealthymonkeys.com)
 255
 256 Configuration of these repositories is beyond the scope of this module and is
 257 left to the user.
 258
 259 # Attribution
 260
 261 The Passenger tuning parameters for the `apache::mod::passenger` Puppet class
 262 was modified by Aaron Hicks (hicksa@landcareresearch.co.nz) for work on the
 263 NeSI Project and the Tuakiri New Zealand Access Federation as a fork from the
 264 PuppetLabs Apache module on GitHub.
 265
 266 * https://github.com/puppetlabs/puppetlabs-apache
 267 * https://github.com/nesi/puppetlabs-apache
 268 * http://www.nesi.org.nz//
 269 * https://tuakiri.ac.nz/confluence/display/Tuakiri/Home
 270
 271 # Copyright and License
 272
 273 Copyright (C) 2012 [Puppet Labs](https://www.puppetlabs.com/) Inc
 274
 275 Puppet Labs can be contacted at: info@puppetlabs.com
 276
 277 Licensed under the Apache License, Version 2.0 (the "License");
 278 you may not use this file except in compliance with the License.
 279 You may obtain a copy of the License at
 280
 281   http://www.apache.org/licenses/LICENSE-2.0
 282
 283 Unless required by applicable law or agreed to in writing, software
 284 distributed under the License is distributed on an "AS IS" BASIS,
 285 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 286 See the License for the specific language governing permissions and
 287 limitations under the License.