make ppc64 chroots on pizzetti
[mirror/dsa-puppet.git] / 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.