diff -r a2342f26c9de -r b0b56e0f8c7f dev/provisioning/modules/apache/README.passenger.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/dev/provisioning/modules/apache/README.passenger.md Fri Jan 15 15:35:00 2016 +0100 @@ -0,0 +1,296 @@ +# Passenger + +Just enabling the Passenger module is insufficient for the use of Passenger in +production. Passenger should be tunable to better fit the environment in which +it is run while being aware of the resources it required. + +To this end the Apache passenger module has been modified to apply system wide +Passenger tuning declarations to `passenger.conf`. Declarations specific to a +virtual host should be passed through when defining a `vhost` (e.g. +`rack_base_uris` parameter on the `apache::vhost` type, check `README.md`). + +Also, general apache module loading parameters can be supplied to enable using +a customized passenger module in place of a default-package-based version of +the module. + +## Operating system support and Passenger versions + +The most important configuration directive for the Apache Passenger module is +`PassengerRoot`. Its value depends on the Passenger version used (2.x, 3.x or +4.x) and on the operating system package from which the Apache Passenger module +is installed. + +The following table summarises the current *default versions* and +`PassengerRoot` settings for the operating systems supported by +puppetlabs-apache: + +OS | Passenger version | `PassengerRoot` +---------------- | ------------------ | ---------------- +Debian 7 | 3.0.13 | /usr +Debian 8 | 4.0.53 | /usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini +Ubuntu 12.04 | 2.2.11 | /usr +Ubuntu 14.04 | 4.0.37 | /usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini +RHEL with EPEL6 | 3.0.21 | /usr/lib/ruby/gems/1.8/gems/passenger-3.0.21 + +As mentioned in `README.md` there are no compatible packages available for +RHEL/CentOS 5 or RHEL/CentOS 7. + +### Configuration files and locations on RHEL/CentOS + +Notice two important points: + +1. The Passenger version packaged in the EPEL repositories may change over time. +2. The value of `PassengerRoot` depends on the Passenger version installed. + +To prevent the puppetlabs-apache module from having to keep up with these +package versions the Passenger configuration files installed by the +packages are left untouched by this module. All configuration is placed in an +extra configuration file managed by puppetlabs-apache. + +This means '/etc/httpd/conf.d/passenger.conf' is installed by the +`mod_passenger` package and contains correct values for `PassengerRoot` and +`PassengerRuby`. Puppet will ignore this file. Additional configuration +directives as described in the remainder of this document are placed in +'/etc/httpd/conf.d/passenger_extra.conf', managed by Puppet. + +This pertains *only* to RHEL/CentOS, *not* Debian and Ubuntu. + +### Third-party and custom Passenger packages and versions + +The Passenger version distributed by the default OS packages may be too old to +be useful. Newer versions may be installed via Gems, from source or from +third-party OS packages. + +Most notably the Passenger developers officially provide Debian packages for a +variety of Debian and Ubuntu releases in the [Passenger APT +repository](https://oss-binaries.phusionpassenger.com/apt/passenger). Read more +about [installing these packages in the offical user +guide](http://www.modrails.com/documentation/Users%20guide%20Apache.html#install_on_debian_ubuntu). + +If you install custom Passenger packages and newer version make sure to set the +directives `PassengerRoot`, `PassengerRuby` and/or `PassengerDefaultRuby` +correctly, or Passenger and Apache will fail to function properly. + +For Passenger 4.x packages on Debian and Ubuntu the `PassengerRoot` directive +should almost universally be set to +`/usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini`. + +## Parameters for `apache::mod::passenger` + +The following class parameters configure Passenger in a global, server-wide +context. + +Example: + +```puppet +class { 'apache::mod::passenger': + passenger_root => '/usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini', + passenger_default_ruby => '/usr/bin/ruby1.9.3', + passenger_high_performance => 'on', + rails_autodetect => 'off', + mod_lib_path => '/usr/lib/apache2/custom_modules', +} +``` + +The general form is using the all lower-case version of the configuration +directive, with underscores instead of CamelCase. + +### Parameters used with passenger.conf + +If you pass a default value to `apache::mod::passenger` it will be ignored and +not passed through to the configuration file. + +#### passenger_root + +The location to the Phusion Passenger root directory. This configuration option +is essential to Phusion Passenger, and allows Phusion Passenger to locate its +own data files. + +The default depends on the Passenger version and the means of installation. See +the above section on operating system support, versions and packages for more +information. + +http://www.modrails.com/documentation/Users%20guide%20Apache.html#_passengerroot_lt_directory_gt + +#### passenger_default_ruby + +This option specifies the default Ruby interpreter to use for web apps as well +as for all sorts of internal Phusion Passenger helper scripts, e.g. the one +used by PassengerPreStart. + +This directive was introduced in Passenger 4.0.0 and will not work in versions +< 4.x. Do not set this parameter if your Passenger version is older than 4.0.0. + +Defaults to `undef` for all operating systems except Ubuntu 14.04, where it is +set to '/usr/bin/ruby'. + +http://www.modrails.com/documentation/Users%20guide%20Apache.html#PassengerDefaultRuby + +#### passenger_ruby + +This directive is the same as `passenger_default_ruby` for Passenger versions +< 4.x and must be used instead of `passenger_default_ruby` for such versions. + +It makes no sense to set `PassengerRuby` for Passenger >= 4.x. That +directive should only be used to override the value of `PassengerDefaultRuby` +on a non-global context, i.e. in ``, ``, `` +and so on. + +Defaults to `/usr/bin/ruby` for all supported operating systems except Ubuntu +14.04, where it is set to `undef`. + +http://www.modrails.com/documentation/Users%20guide%20Apache.html#PassengerRuby + +#### passenger_high_performance + +Default is `off`. When turned `on` Passenger runs in a higher performance mode +that can be less compatible with other Apache modules. + +http://www.modrails.com/documentation/Users%20guide%20Apache.html#PassengerHighPerformance + +#### passenger_max_pool_size + +Sets the maximum number of Passenger application processes that may +simultaneously run. The default value is 6. + +http://www.modrails.com/documentation/Users%20guide%20Apache.html#_passengermaxpoolsize_lt_integer_gt + +#### passenger_pool_idle_time + +The maximum number of seconds a Passenger Application process will be allowed +to remain idle before being shut down. The default value is 300. + +http://www.modrails.com/documentation/Users%20guide%20Apache.html#PassengerPoolIdleTime + +#### passenger_max_requests + +The maximum number of request a Passenger application will process before being +restarted. The default value is 0, which indicates that a process will only +shut down if the Pool Idle Time (see above) expires. + +http://www.modrails.com/documentation/Users%20guide%20Apache.html#PassengerMaxRequests + +#### passenger_spawn_method + +Sets the method by which Ruby application processes are spawned. Default is 'smart', +which caches code using the app preloader. + +Passenger >= 4.0 renamed `conservative` to `direct` and `smart-lv2` to `smart`. + +https://www.phusionpassenger.com/documentation/Users%20guide%20Apache.html#PassengerSpawnMethod + +#### passenger_stat_throttle_rate + +Sets how often Passenger performs file system checks, at most once every _x_ +seconds. Default is 0, which means the checks are performed with every request. + +http://www.modrails.com/documentation/Users%20guide%20Apache.html#_passengerstatthrottlerate_lt_integer_gt + +#### rack_autodetect + +Should Passenger automatically detect if the document root of a virtual host is +a Rack application. Not set by default (`undef`). Note that this directive has +been removed in Passenger 4.0.0 and `PassengerEnabled` should be used instead. +Use this directive only on Passenger < 4.x. + +http://www.modrails.com/documentation/Users%20guide%20Apache.html#_rackautodetect_lt_on_off_gt + +#### rails_autodetect + +Should Passenger automatically detect if the document root of a virtual host is +a Rails application. Not set by default (`undef`). Note that this directive +has been removed in Passenger 4.0.0 and `PassengerEnabled` should be used +instead. Use this directive only on Passenger < 4.x. + +http://www.modrails.com/documentation/Users%20guide%20Apache.html#_railsautodetect_lt_on_off_gt + +#### passenger_use_global_queue + +Allows toggling of PassengerUseGlobalQueue. NOTE: PassengerUseGlobalQueue is +the default in Passenger 4.x and the versions >= 4.x have disabled this +configuration option altogether. Use with caution. + +#### passenger_app_env + +Sets the global default `PassengerAppEnv` for Passenger applications. Not set by +default (`undef`) and thus defaults to Passenger's built-in value of 'production'. +This directive can be overridden in an `apache::vhost` resource. + +https://www.phusionpassenger.com/documentation/Users%20guide%20Apache.html#PassengerAppEnv + +### Parameters used to load the module + +Unlike the tuning parameters specified above, the following parameters are only +used when loading customized passenger modules. + +#### mod_package + +Allows overriding the default package name used for the passenger module +package. + +#### mod_package_ensure + +Allows overriding the package installation setting used by puppet when +installing the passenger module. The default is 'present'. + +#### mod_id + +Allows overriding the value used by apache to identify the passenger module. +The default is 'passenger_module'. + +#### mod_lib_path + +Allows overriding the directory path used by apache when loading the passenger +module. The default is the value of `$apache::params::lib_path`. + +#### mod_lib + +Allows overriding the library file name used by apache when loading the +passenger module. The default is 'mod_passenger.so'. + +#### mod_path + +Allows overriding the full path to the library file used by apache when loading +the passenger module. The default is the concatenation of the `mod_lib_path` +and `mod_lib` parameters. + +## Dependencies + +RedHat-based systems will need to configure additional package repositories in +order to install Passenger, specifically: + +* [Extra Packages for Enterprise Linux](https://fedoraproject.org/wiki/EPEL) +* [Phusion Passenger](http://passenger.stealthymonkeys.com) + +Configuration of these repositories is beyond the scope of this module and is +left to the user. + +## Attribution + +The Passenger tuning parameters for the `apache::mod::passenger` Puppet class +was modified by Aaron Hicks (hicksa@landcareresearch.co.nz) for work on the +NeSI Project and the Tuakiri New Zealand Access Federation as a fork from the +PuppetLabs Apache module on GitHub. + +* https://github.com/puppetlabs/puppetlabs-apache +* https://github.com/nesi/puppetlabs-apache +* http://www.nesi.org.nz// +* https://tuakiri.ac.nz/confluence/display/Tuakiri/Home + +## Copyright and License + +Copyright (C) 2012 [Puppet Labs](https://www.puppetlabs.com/) Inc + +Puppet Labs can be contacted at: info@puppetlabs.com + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License.