|
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_spawn_method |
|
174 |
|
175 Sets the method by which Ruby application processes are spawned. Default is 'smart', |
|
176 which caches code using the app preloader. |
|
177 |
|
178 Passenger >= 4.0 renamed `conservative` to `direct` and `smart-lv2` to `smart`. |
|
179 |
|
180 https://www.phusionpassenger.com/documentation/Users%20guide%20Apache.html#PassengerSpawnMethod |
|
181 |
|
182 #### passenger_stat_throttle_rate |
|
183 |
|
184 Sets how often Passenger performs file system checks, at most once every _x_ |
|
185 seconds. Default is 0, which means the checks are performed with every request. |
|
186 |
|
187 http://www.modrails.com/documentation/Users%20guide%20Apache.html#_passengerstatthrottlerate_lt_integer_gt |
|
188 |
|
189 #### rack_autodetect |
|
190 |
|
191 Should Passenger automatically detect if the document root of a virtual host is |
|
192 a Rack application. Not set by default (`undef`). Note that this directive has |
|
193 been removed in Passenger 4.0.0 and `PassengerEnabled` should be used instead. |
|
194 Use this directive only on Passenger < 4.x. |
|
195 |
|
196 http://www.modrails.com/documentation/Users%20guide%20Apache.html#_rackautodetect_lt_on_off_gt |
|
197 |
|
198 #### rails_autodetect |
|
199 |
|
200 Should Passenger automatically detect if the document root of a virtual host is |
|
201 a Rails application. Not set by default (`undef`). Note that this directive |
|
202 has been removed in Passenger 4.0.0 and `PassengerEnabled` should be used |
|
203 instead. Use this directive only on Passenger < 4.x. |
|
204 |
|
205 http://www.modrails.com/documentation/Users%20guide%20Apache.html#_railsautodetect_lt_on_off_gt |
|
206 |
|
207 #### passenger_use_global_queue |
|
208 |
|
209 Allows toggling of PassengerUseGlobalQueue. NOTE: PassengerUseGlobalQueue is |
|
210 the default in Passenger 4.x and the versions >= 4.x have disabled this |
|
211 configuration option altogether. Use with caution. |
|
212 |
|
213 #### passenger_app_env |
|
214 |
|
215 Sets the global default `PassengerAppEnv` for Passenger applications. Not set by |
|
216 default (`undef`) and thus defaults to Passenger's built-in value of 'production'. |
|
217 This directive can be overridden in an `apache::vhost` resource. |
|
218 |
|
219 https://www.phusionpassenger.com/documentation/Users%20guide%20Apache.html#PassengerAppEnv |
|
220 |
|
221 ### Parameters used to load the module |
|
222 |
|
223 Unlike the tuning parameters specified above, the following parameters are only |
|
224 used when loading customized passenger modules. |
|
225 |
|
226 #### mod_package |
|
227 |
|
228 Allows overriding the default package name used for the passenger module |
|
229 package. |
|
230 |
|
231 #### mod_package_ensure |
|
232 |
|
233 Allows overriding the package installation setting used by puppet when |
|
234 installing the passenger module. The default is 'present'. |
|
235 |
|
236 #### mod_id |
|
237 |
|
238 Allows overriding the value used by apache to identify the passenger module. |
|
239 The default is 'passenger_module'. |
|
240 |
|
241 #### mod_lib_path |
|
242 |
|
243 Allows overriding the directory path used by apache when loading the passenger |
|
244 module. The default is the value of `$apache::params::lib_path`. |
|
245 |
|
246 #### mod_lib |
|
247 |
|
248 Allows overriding the library file name used by apache when loading the |
|
249 passenger module. The default is 'mod_passenger.so'. |
|
250 |
|
251 #### mod_path |
|
252 |
|
253 Allows overriding the full path to the library file used by apache when loading |
|
254 the passenger module. The default is the concatenation of the `mod_lib_path` |
|
255 and `mod_lib` parameters. |
|
256 |
|
257 ## Dependencies |
|
258 |
|
259 RedHat-based systems will need to configure additional package repositories in |
|
260 order to install Passenger, specifically: |
|
261 |
|
262 * [Extra Packages for Enterprise Linux](https://fedoraproject.org/wiki/EPEL) |
|
263 * [Phusion Passenger](http://passenger.stealthymonkeys.com) |
|
264 |
|
265 Configuration of these repositories is beyond the scope of this module and is |
|
266 left to the user. |
|
267 |
|
268 ## Attribution |
|
269 |
|
270 The Passenger tuning parameters for the `apache::mod::passenger` Puppet class |
|
271 was modified by Aaron Hicks (hicksa@landcareresearch.co.nz) for work on the |
|
272 NeSI Project and the Tuakiri New Zealand Access Federation as a fork from the |
|
273 PuppetLabs Apache module on GitHub. |
|
274 |
|
275 * https://github.com/puppetlabs/puppetlabs-apache |
|
276 * https://github.com/nesi/puppetlabs-apache |
|
277 * http://www.nesi.org.nz// |
|
278 * https://tuakiri.ac.nz/confluence/display/Tuakiri/Home |
|
279 |
|
280 ## Copyright and License |
|
281 |
|
282 Copyright (C) 2012 [Puppet Labs](https://www.puppetlabs.com/) Inc |
|
283 |
|
284 Puppet Labs can be contacted at: info@puppetlabs.com |
|
285 |
|
286 Licensed under the Apache License, Version 2.0 (the "License"); |
|
287 you may not use this file except in compliance with the License. |
|
288 You may obtain a copy of the License at |
|
289 |
|
290 http://www.apache.org/licenses/LICENSE-2.0 |
|
291 |
|
292 Unless required by applicable law or agreed to in writing, software |
|
293 distributed under the License is distributed on an "AS IS" BASIS, |
|
294 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
|
295 See the License for the specific language governing permissions and |
|
296 limitations under the License. |