passenger 5.0.14 → 5.0.15

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of passenger might be problematic. Click here for more details.

Files changed (70) hide show
  1. checksums.yaml +8 -8
  2. checksums.yaml.gz.asc +7 -7
  3. data.tar.gz.asc +7 -7
  4. data/CHANGELOG +9 -0
  5. data/INSTALL.md +1 -1
  6. data/LICENSE +1 -1
  7. data/README.md +1 -1
  8. data/bin/passenger-install-apache2-module +6 -10
  9. data/bin/passenger-install-nginx-module +6 -9
  10. data/doc/CloudLicensingConfiguration.html +1 -216
  11. data/doc/CloudLicensingConfiguration.txt.md +1 -192
  12. data/doc/Design and Architecture.html +4 -4
  13. data/doc/Design and Architecture.txt +4 -4
  14. data/doc/ServerOptimizationGuide.html +1 -489
  15. data/doc/ServerOptimizationGuide.txt.md +1 -399
  16. data/doc/Users guide Apache.html +594 -6720
  17. data/doc/Users guide Apache.idmap.txt +15 -12
  18. data/doc/Users guide Apache.txt +113 -2047
  19. data/doc/Users guide Nginx.html +565 -6720
  20. data/doc/Users guide Nginx.idmap.txt +15 -12
  21. data/doc/Users guide Nginx.txt +94 -1862
  22. data/doc/Users guide Standalone.html +53 -2183
  23. data/doc/Users guide Standalone.idmap.txt +9 -6
  24. data/doc/Users guide Standalone.txt +16 -360
  25. data/doc/Users guide.html +3 -145
  26. data/doc/Users guide.txt +2 -54
  27. data/doc/users_guide_snippets/analysis_and_system_maintenance.txt +36 -175
  28. data/doc/users_guide_snippets/appendix_c_spawning_methods.txt +9 -215
  29. data/doc/users_guide_snippets/environment_variables.txt +11 -243
  30. data/doc/users_guide_snippets/installation.txt +66 -946
  31. data/doc/users_guide_snippets/rackup_specifications.txt +1 -75
  32. data/doc/users_guide_snippets/support_information.txt +1 -48
  33. data/doc/users_guide_snippets/tips.txt +103 -704
  34. data/doc/users_guide_snippets/troubleshooting/default.txt +16 -130
  35. data/doc/users_guide_snippets/troubleshooting/rails.txt +15 -12
  36. data/doc/users_guide_snippets/under_the_hood/relationship_with_ruby.txt +2 -113
  37. data/ext/apache2/Configuration.hpp +2 -2
  38. data/ext/apache2/Hooks.cpp +2 -2
  39. data/ext/common/AgentsStarter.h +18 -10
  40. data/ext/common/ApplicationPool2/ErrorRenderer.h +0 -3
  41. data/ext/common/ApplicationPool2/Options.h +8 -1
  42. data/ext/common/Constants.h +3 -9
  43. data/ext/common/agent/Core/RequestHandler/InitRequest.cpp +2 -0
  44. data/ext/common/agent/Watchdog/Main.cpp +1 -1
  45. data/ext/nginx/ContentHandler.c +2 -3
  46. data/ext/nginx/config +2 -2
  47. data/lib/phusion_passenger.rb +1 -22
  48. data/lib/phusion_passenger/abstract_installer.rb +10 -10
  49. data/lib/phusion_passenger/config/agent_compiler.rb +5 -5
  50. data/lib/phusion_passenger/config/nginx_engine_compiler.rb +4 -4
  51. data/lib/phusion_passenger/config/validate_install_command.rb +3 -3
  52. data/lib/phusion_passenger/constants.rb +1 -5
  53. data/lib/phusion_passenger/loader_shared_helpers.rb +16 -5
  54. data/lib/phusion_passenger/platform_info/apache_detector.rb +2 -2
  55. data/lib/phusion_passenger/public_api.rb +11 -2
  56. data/lib/phusion_passenger/request_handler/thread_handler.rb +2 -3
  57. data/lib/phusion_passenger/ruby_core_io_enhancements.rb +4 -1
  58. data/lib/phusion_passenger/standalone/start_command.rb +1 -1
  59. data/resources/oss-binaries.phusionpassenger.com.crt +124 -0
  60. data/resources/templates/apache2/deployment_example.txt.erb +5 -23
  61. data/resources/templates/apache2/installing_against_a_different_apache.txt.erb +3 -4
  62. data/resources/templates/apache2/possible_solutions_for_compilation_and_installation_problems.txt.erb +3 -3
  63. data/resources/templates/apache2/rpm_installation_recommended.txt.erb +1 -1
  64. data/resources/templates/installer_common/low_amount_of_memory_warning.txt.erb +4 -5
  65. data/resources/templates/nginx/deployment_example.txt.erb +5 -17
  66. data/resources/templates/nginx/possible_solutions_for_compilation_and_installation_problems.txt.erb +3 -3
  67. data/resources/templates/standalone/config.erb +1 -1
  68. data/resources/templates/undisclosed_error.html.template +4 -11
  69. metadata +2 -2
  70. metadata.gz.asc +7 -7
@@ -1,75 +1 @@
1
- This subsection shows example 'config.ru' files for various web frameworks.
2
-
3
- ==== Camping ====
4
- ------------------------------------------------------
5
- require 'rubygems'
6
- require 'rack'
7
- require 'camping'
8
-
9
- ##### Begin Camping application
10
- Camping.goes :Blog
11
-
12
- ...your application code here...
13
- ##### End Camping application
14
-
15
- run Rack::Adapter::Camping.new(Blog)
16
- ------------------------------------------------------
17
-
18
- For Camping versions 2.0 and up, using `run Blog` as the final line will do.
19
-
20
- ==== Halcyon ====
21
- ------------------------------------------------------
22
- require 'rubygems'
23
- require 'halcyon'
24
- $LOAD_PATH.unshift(Halcyon.root / 'lib')
25
- Halcyon::Runner.load_config Halcyon.root/'config'/'config.yml'
26
- run Halcyon::Runner.new
27
- ------------------------------------------------------
28
-
29
- ==== Mack ====
30
- ------------------------------------------------------
31
- ENV["MACK_ENV"] = ENV["RACK_ENV"]
32
- load("Rakefile")
33
- require 'rubygems'
34
- require 'mack'
35
- run Mack::Utils::Server.build_app
36
- ------------------------------------------------------
37
-
38
- ==== Merb ====
39
- ------------------------------------------------------
40
- require 'rubygems'
41
- require 'merb-core'
42
-
43
- Merb::Config.setup(
44
- :merb_root => ::File.expand_path(::File.dirname(__FILE__)),
45
- :environment => ENV['RACK_ENV']
46
- )
47
- Merb.environment = Merb::Config[:environment]
48
- Merb.root = Merb::Config[:merb_root]
49
- Merb::BootLoader.run
50
-
51
- run Merb::Rack::Application.new
52
- ------------------------------------------------------
53
-
54
- ==== Ramaze ====
55
- ------------------------------------------------------
56
- require "rubygems"
57
- require "ramaze"
58
- Ramaze.trait[:essentials].delete Ramaze::Adapter
59
- require "start"
60
- Ramaze.start!
61
- run Ramaze::Adapter::Base
62
- ------------------------------------------------------
63
-
64
- ==== Sinatra ====
65
- ------------------------------------------------------
66
- require 'rubygems'
67
- require 'sinatra'
68
-
69
- set :environment, ENV['RACK_ENV'].to_sym
70
- disable :run, :reload
71
-
72
- require 'app.rb'
73
-
74
- run Sinatra::Application
75
- ------------------------------------------------------
1
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/config_ru.html
@@ -1,53 +1,6 @@
1
1
  === Supported operating systems and languages ===
2
2
 
3
- Phusion Passenger works on almost any POSIX-compliant operating system. In other
4
- words: practically any operating system on earth, except Microsoft Windows.
5
-
6
- Supported operating systems:
7
-
8
- [options="header"]
9
- |==================================================
10
- | OS | Minimum version
11
- | Ubuntu | 10.04
12
- | Debian | 6
13
- | Red Hat, CentOS | 5
14
- | Amazon Linux | All versions supported
15
- | Mac OS X | 10.8 Mountain Lion
16
- | FreeBSD | 8
17
- | OpenBSD | 5.2
18
- | Other Unix | -
19
- |==================================================
20
-
21
- "Other Unix" is supported on a "best-effort" basis. We do not regularly check whether Phusion Passenger still works on other Unices, but if users report issues then we'll try to address them.
22
-
23
- Supported architectures:
24
-
25
- [options="header"]
26
- |==================================================
27
- | Architecture | Notes
28
- | x86 (32-bit) | -
29
- | x86_64 (64-bit) | -
30
- | Other | Supported on a "best-effort" basis.
31
- |==================================================
32
-
33
- Supported languages and frameworks:
34
-
35
- [options="header"]
36
- |==================================================
37
- | Language/framework | Minimum version
38
- | Ruby (MRI) | 1.8.5
39
- | JRuby | 1.7.0
40
- | Rubinius | 2.2.0
41
- | Ruby on Rails | 2.3
42
- | Python | 2.6
43
- | Node.js/io.js | 0.10
44
- | Meteor | 0.6
45
- |==================================================
46
-
47
- If you run into any issues, please
48
- link:https://github.com/phusion/passenger/issues[report a bug]
49
- or
50
- link:http://groups.google.com/group/phusion-passenger[join our discussion forum].
3
+ This documentation has moved. https://www.phusionpassenger.com/library/install/supported_operating_systems_and_languages.html
51
4
 
52
5
  [[where_to_get_support]]
53
6
  === Where to get support ===
@@ -1,190 +1,77 @@
1
1
  [[user_switching]]
2
2
  === User Switching (security feature) ===
3
3
 
4
- Phusion Passenger supports automatic 'user switching': by default, it attempts to run applications as the "right" user, instead of running all applications as the same user.
5
-
6
- To better understand the problem, let us consider the situation with PHP.
7
- There is a problem that plagues most PHP web hosts, namely the fact that all PHP
8
- applications are run in the same user context as the web server. So for
9
- example, Joe's PHP application will be able to read Jane's PHP application's
10
- passwords. This is obviously undesirable on many servers.
11
-
12
- Phusion Passenger's 'user switching' feature solves this problem. Applications are
13
- run as the owner of their "startup file". For Ruby apps, the startup file is
14
- `config.ru` (Rack and Rails >= 3) or `config/environment.rb` (Rails 1 and 2). For
15
- Python apps, the startup file is `passenger_wsgi.py`. So suppose that `config.ru`
16
- is owned by user 'joe', then Phusion Passenger will spawn the corresponding
17
- application as 'joe' as well. The exact rules are a little bit more complicated,
18
- and they're explained further down in this section.
19
-
20
- ==== Requirements
21
-
22
- User switching is only enabled when all of the following conditions are met:
23
-
24
- - When not using <<flying_passenger,Flying Passenger>> (this is probably the case):
25
- * The
26
4
  ifdef::apache[]
27
- <<PassengerUserSwitching,PassengerUserSwitching>>
5
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/user_sandboxing.html
28
6
  endif::[]
29
7
  ifdef::nginx[]
30
- <<PassengerUserSwitching,passenger_user_switching>>
8
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/user_sandboxing.html
9
+ endif::[]
10
+ ifdef::standalone[]
11
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/standalone/user_sandboxing.html
31
12
  endif::[]
32
- option must be enabled.
33
- * The web server's control process must have root privileges. This is the case on most installations.
34
- - When using <<flying_passenger,Flying Passenger>>:
35
- * The Flying Passenger daemon must be run with root privileges.
36
-
37
- ==== Effects
38
13
 
39
- When not using Flying Passenger, the following table illustrates the effect for different combinations of the requirements.
14
+ ==== Requirements
40
15
 
41
- |==========================================================
42
16
  ifdef::apache[]
43
- | | **PassengerUserSwitching on** | **PassengerUserSwitching off**
17
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/user_sandboxing.html
44
18
  endif::[]
45
19
  ifdef::nginx[]
46
- | | **passenger_user_switching on** | **passenger_user_switching off**
47
- endif::[]
48
- | **Web server has root privileges**
49
- | User switching enabled.
50
- | User switching disabled. Apps are run as
51
- ifdef::apache[]
52
- <<PassengerDefaultUser,PassengerDefaultUser>> and
53
- <<PassengerDefaultGroup,PassengerDefaultGroup>>.
20
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/user_sandboxing.html
54
21
  endif::[]
55
- ifdef::nginx[]
56
- <<PassengerDefaultUser,passenger_default_user>> and
57
- <<PassengerDefaultGroup,passenger_default_group>>.
22
+ ifdef::standalone[]
23
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/standalone/user_sandboxing.html
58
24
  endif::[]
59
- | **Web server has no root privileges**
60
- | User switching disabled. Apps are run as the web server's user.
61
- | User switching disabled. Apps are run as the web server's user.
62
- |==========================================================
63
-
64
- When using Flying Passenger, the effect is as follows:
65
25
 
66
- |==========================================================
67
- | **Daemon run with root privileges** | User switching enabled.
68
- | **Daemon run without root privileges** | User switching disabled. Apps are run as the daemon's user.
69
- |==========================================================
70
-
71
- When user switching is enabled, the following rules are followed to determine what user an application should be run as. The first matching rule is the rule that will be followed.
26
+ ==== Effects
72
27
 
73
- 1. If
74
28
  ifdef::apache[]
75
- <<PassengerUser,PassengerUser>> or
76
- <<PassengerGroup,PassengerGroup>>
29
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/user_sandboxing.html
77
30
  endif::[]
78
31
  ifdef::nginx[]
79
- <<PassengerUser,passenger_user>> or
80
- <<PassengerGroup,passenger_group>>
32
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/user_sandboxing.html
81
33
  endif::[]
82
- are set, then the application will be run as the specified user/group. Thus, these options are a good way to override user switching settings.
83
- 2. If the startup file is owned by root or an unknown user, then the application will run as the user specified by
84
- ifdef::apache[]
85
- <<PassengerDefaultUser,PassengerDefaultUser>> and
86
- <<PassengerDefaultGroup,PassengerDefaultGroup>>.
87
- endif::[]
88
- ifdef::nginx[]
89
- <<PassengerDefaultUser,passenger_default_user>> and
90
- <<PassengerDefaultGroup,passenger_default_group>>.
34
+ ifdef::standalone[]
35
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/standalone/user_sandboxing.html
91
36
  endif::[]
92
- 3. Otherwise, the application is run as the owner of the startup file.
93
37
 
94
38
  ==== Caveats & troubleshooting
95
39
 
96
- If your application regularly encounters permission errors or fails to find certain files, then this is an indication that your application is started as a user that you did not intent it to be run as. Other symptoms include:
97
-
98
- - The application fails to start because Bundler complains that it cannot find gems. This probably indicates that Bundler does not have read access to the directory that contains Bundler-installed gems.
99
- - The application fails to start and its error message mentions the path '/nonexistent'. This probably indicates that your application is started as the 'nobody' user. This is because on many systems, the 'nobody' user's home directory is '/nonexistent'.
100
-
101
- To check whether it is indeed the case that your application is started as a different user than you intended to, see <<finding_out_app_user,Finding out what user an application is running as>>.
102
-
103
- The most likely reason why your application is started as 'nobody' is probably because your startup file is owned by 'root', by 'nobody' or by an unknown user. To fix this, change the owner of the startup file to the owner that you want to run the application as.
104
-
105
- Whatever user your application runs as, it must have read access to the <<application_root,application root>>, and read/write access to the application's 'logs' directory.
106
-
107
- [[user_switching_rpm_caveats]]
108
- ==== Red Hat and CentOS caveats
109
-
110
- NOTE: This information only applies if you installed Passenger through the RPM packages provided by Phusion. If you did not installed Passenger through the RPM packages provided by Phusion, then you can ignore this section.
111
-
112
- If you installed Passenger through Phusion's RPM packages, and you want to disable user switching, then you must also change <<PassengerInstanceRegistryDir,the location of the instance registry directory>>.
113
-
114
- This is because our RPMs configure the default instance registry directory to `/var/run/passenger-instreg`, which is only writable by root. If you disable user switching, then the Passenger processes will run as
115
40
  ifdef::apache[]
116
- <<PassengerDefaultUser,PassengerDefaultUser>>,
41
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/user_sandboxing.html
117
42
  endif::[]
118
43
  ifdef::nginx[]
119
- <<PassengerDefaultUser,passenger_default_user>>,
44
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/user_sandboxing.html
45
+ endif::[]
46
+ ifdef::standalone[]
47
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/standalone/user_sandboxing.html
120
48
  endif::[]
121
- which (as long as it's not root) won't be able to write to that directory.
122
-
123
- Note that any alternative instance registry directory must have the proper SELinux context, allowing the web server to read and write to it. We recommend that you create a directory `/var/lib/passenger-instreg` and give it the label `var_run_t`:
124
49
 
125
- ------------------------------------------
126
- sudo mkdir /var/lib/passenger-instreg
127
- sudo chcon -t var_run_t /var/lib/passenger-instreg
128
- ------------------------------------------
50
+ [[user_switching_rpm_caveats]]
51
+ ==== Red Hat and CentOS caveats
129
52
 
130
53
  ifdef::apache[]
131
- Then, in your Apache config file:
132
-
133
- ------------------------------------------
134
- PassengerInstanceRegistryDir /var/lib/passenger-instreg
135
- ------------------------------------------
54
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/user_sandboxing.html
136
55
  endif::[]
137
56
  ifdef::nginx[]
138
- Then, in your Nginx config file:
139
-
140
- ------------------------------------------
141
- passenger_instance_registry_dir /var/lib/passenger-instreg;
142
- ------------------------------------------
57
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/user_sandboxing.html
58
+ endif::[]
59
+ ifdef::standalone[]
60
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/standalone/user_sandboxing.html
143
61
  endif::[]
144
62
 
145
63
  [[finding_out_app_user]]
146
64
  ==== Finding out what user an application is running as
147
65
 
148
- To find our what user an application is started as, first access its URL in your browser so that Phusion Passenger starts the application. For example:
149
-
150
- ----------------------------------
151
- http://www.example.local/
152
- ----------------------------------
153
-
154
- The application will now either successfully start or fail to start. If it fails to start then you will see an error page that tells you what user the application was being started as. If you do not see the error page in the browser then set
155
66
  ifdef::apache[]
156
- <<PassengerFriendlyErrorPages,PassengerFriendlyErrorPages>>
67
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/user_sandboxing.html
157
68
  endif::[]
158
69
  ifdef::nginx[]
159
- <<PassengerFriendlyErrorPages,passenger_friendly_error_pages>>
70
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/user_sandboxing.html
71
+ endif::[]
72
+ ifdef::standalone[]
73
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/standalone/user_sandboxing.html
160
74
  endif::[]
161
- on.
162
-
163
- If the application successfully started, then run `passenger-status` to find the process's PID:
164
-
165
- ------------------------------------------------
166
- .---------- General information -----------
167
- Max pool size : 6
168
- Processes : 1
169
- Requests in top-level queue : 0
170
-
171
- .---------- Application groups -----------
172
- /webapps/example.local#default:
173
- App root: /webapps/example.local
174
- Requests in queue: 0
175
- * PID: 16915 Sessions: 0 Processed: 1 Uptime: 2s
176
- CPU: 0% Memory : 9M Last used: 2s ago
177
- ------------------------------------------------
178
-
179
- In the above example we see that the PID is 16915. Next, use 'ps' to find out the user that it is running as:
180
-
181
- --------------------------------------------------
182
- # ps -o pid,user,comm -p 16915
183
- PID USER COMM
184
- 16915 phusion Passenger RackApp: /webapps/example.local
185
- --------------------------------------------------
186
-
187
- As you can see, the application in this example is being run as user 'phusion'.
188
75
 
189
76
 
190
77
  [[reducing_memory_usage]]
@@ -198,71 +85,25 @@ Phusion Passenger automatically leverages operating system virtual memory copy-o
198
85
  [[tuning_sse_websockets]]
199
86
  === Tuning for Server Sent Events and WebSockets ===
200
87
 
201
- Phusion Passenger supports Server Sent Events (SSE) and WebSockets out of the box with no configuration, but there are some things you need to know.
202
-
203
- First, WebSockets are link:https://github.com/phusion/passenger/issues/1202[not yet supported when using the Apache integration mode].
204
-
205
- Second, for Ruby apps only, you need to insert a configuration snippet inside your `config.ru`:
206
-
207
- [code,ruby]
208
- ----------------------------------------------------------
209
- if defined?(PhusionPassenger)
210
- PhusionPassenger.advertised_concurrency_level = 0
211
- end
212
- ----------------------------------------------------------
213
-
214
- [NOTE]
215
- ==========================================================
216
- This snippet tells Passenger that your Ruby app will handle SSE and WebSockets. In response, Passenger will adjust the connection concurrency settings for your app. Without this configuration snippet, SSE and WebSockets still work, but with degraded performance.
217
-
218
- This configuration snippet is currently necessary because of the way Passenger is implemented. We are link:https://github.com/phusion/passenger/issues/1195[working on improving this mechanism]. One day, the above configuration snippet will no longer be necessary. For now, you should include the above configuration snippet for optimal SSE and WebSocket performance.
219
- ==========================================================
220
-
221
- Finally, you can find Passenger SSE and WebSocket demo apps on link:https://www.phusionpassenger.com/documentation_and_support[the Passenger documentation overview page], under section "Demos".
88
+ ifdef::apache[]
89
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/apache/tuning_sse_and_websockets.html
90
+ endif::[]
91
+ ifdef::nginx[]
92
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/nginx/tuning_sse_and_websockets.html
93
+ endif::[]
94
+ ifdef::standalone[]
95
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/config/standalone/tuning_sse_and_websockets.html
96
+ endif::[]
222
97
 
223
98
  [[bundler_support]]
224
99
  === Bundler support ===
225
100
 
226
- Phusion Passenger has automatic support for link:http://gembundler.com/git.html[Bundler].
227
- The support consists of loading your application under the environment defined by your
228
- Gemfile. In other words, Phusion Passenger loads your application as if 'bundle exec' was used.
229
-
230
- The Bundler support works as follows:
231
-
232
- - If you have a '.bundle/environment.rb' in your application root, then Phusion
233
- Passenger will require that file before loading your application.
234
- - Otherwise, if you have a 'Gemfile', then Phusion Passenger will automatically call
235
- `Bundler.setup()` before loading your application.
236
-
237
- It's possible that your application also calls `Bundler.setup` during loading, e.g. in
238
- 'config.ru' or in 'config/boot.rb'. This is the case with Rails 3, and is also the case if you
239
- modified your 'config/boot.rb' according to the
240
- link:http://gembundler.com/rails23.html[Bundler Rails 2.3 instructions].
241
- This leads to `Bundler.setup` being called twice, once before the application startup file
242
- is required and once during application startup. However this is harmless and doesn't
243
- have any negative effects.
244
-
245
- Phusion Passenger assumes that you're using Bundler >= 0.9.5. If you don't want Phusion
246
- Passenger to run its Bundler support code, e.g. because you need to use an older version
247
- of Bundler with an incompatible API or because you use a system other than Bundler, then
248
- you can override Phusion Passenger's Bundler support code by creating an empty file
249
- 'config/setup_load_paths.rb'. If this file exists then it will be required before loading
250
- the application startup file. In this file you can do whatever you need to setup Bundler
251
- or a similar system.
101
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/ruby/bundler.html
252
102
 
253
103
  [[add_passenger_to_gemfile]]
254
104
  ==== Does Phusion Passenger itself need to be added to the Gemfile?
255
105
 
256
- It is never necessary to add Phusion Passenger to the application's Gemfile. In case of Phusion Passenger Standalone, it is not necessary to execute the `passenger` command through `bundle exec`. The reason for this is because Phusion Passenger automatically loads the Gemfile environment. Most other Ruby application servers do not automatically load the Gemfile environment, which is why they must be added to the Gemfile and be executed with `bundle exec`.
257
-
258
- Even when your application uses any of the Phusion Passenger APIs, you still do not need to add Phusion Passenger to the Gemfile. The only thing you need to do is to put Phusion Passenger API calls inside `if` blocks that check whether Phusion Passenger is active, by checking whether the `PhusionPassenger` namespace is defined:
259
-
260
- [code,ruby]
261
- ------------------------------------
262
- if defined?(PhusionPassenger)
263
- ...
264
- end
265
- ------------------------------------
106
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/ruby/bundler.html#does-passenger-itself-need-to-be-added-to-the-gemfile
266
107
 
267
108
  === Installing multiple Ruby on Rails versions ===
268
109
 
@@ -342,562 +183,120 @@ link:http://api.rubyonrails.org/classes/ActionView/Helpers/AssetTagHelper.html[t
342
183
 
343
184
  === Out-of-Band Work and Out-of-Band Garbage Collection
344
185
 
345
- **Available since Phusion Passenger 4.0.0.**
346
-
347
- **At this time, this feature is only available on Ruby.**
348
-
349
- The Out-of-Band Work feature allows you to run arbitrary long-running tasks outside normal request cycles. This works by letting current requests to the process finish, then telling the process to perform the out-of-band work, then resuming passing requests to the process after said work is finished.
350
-
351
- A specific (and perhaps primary) use case of of Out-of-Band Work is *Out-of-Band Garbage Collection*. The garbage collector is run outside normal request cycles so that garbage collection runs inside normal request cycles can finish a lot faster. This can potentially save tens to hundreds of milliseconds of latency in requests.
352
-
353
- Because Out-of-Band Work is implemented at the Phusion Passenger inter-process request routing level, and not by, say, spawning a thread inside the application process, Out-of-Band Work has the following useful properties:
354
-
355
- - It works well even with tasks that can pause all threads. The MRI Ruby garbage collector is a stop-the-world mark-and-sweep garbage collector.
356
- - Phusion Passenger can spawn more processes as necessary, in order to prevent situations in which all application processes are busy performing out-of-band work. Phusion Passenger guarantees that there's at least one process that's ready to process requests.
357
- - Phusion Passenger guarantees that no more than 1 process is performing out-of-band work at the same time.
358
-
359
- Applications can use Out-of-Band Work as follows:
360
-
361
- 1. Ensure that
362
- ifdef::apache[]
363
- <<PassengerMaxPoolSize,PassengerMaxPoolSize>>
364
- and
365
- <<PassengerMinInstances,PassengerMinInstances>>
366
- endif::[]
367
- ifdef::nginx[]
368
- <<PassengerMaxPoolSize,passenger_max_pool_size>>
369
- and
370
- <<PassengerMinInstances,passenger_min_instances>>
371
- endif::[]
372
- are both larger than 1. Out-of-band work only works if there are at least 2 application processes.
373
- 2. Request out-of-band work by outputting the `!~Request-OOB-Work` header during a request. It does not matter what the value is. At this time, it is not possible to request out-of-band work from outside requests.
374
- 3. You can actually perform out-of-band work when you receive a `:oob_work` Phusion Passenger event.
375
-
376
- Note that even though you can request out-of-band work, there's no guarantee that Phusion Passenger will send an `oob_work` event in a timely manner, if at all. It is also possible that Phusion Passenger sends an `oob_work` event without you ever having requested one. This latter could for example happen if the OOB work is administrator-initiated. Do not make any assumptions in your code.
377
-
378
- Here's an example which implements out-of-band garbage collection using the Out-of-Band framework. This example code doesn't do anything when the code is not being run in Phusion Passenger, thanks to the `if` block.
379
-
380
- [source, ruby]
381
- -------------------------------------------------
382
- # Somewhere in a controller method:
383
- # Tell Phusion Passenger we want to perform OOB work.
384
- response.headers["!~Request-OOB-Work"] = "true"
385
-
386
- # Somewhere during application initialization:
387
- if defined?(PhusionPassenger)
388
- PhusionPassenger.on_event(:oob_work) do
389
- # Phusion Passenger has told us that we're ready to perform OOB work.
390
- t0 = Time.now
391
- GC.start
392
- Rails.logger.info "Out-Of-Bound GC finished in #{Time.now - t0} sec"
393
- end
394
- end
395
- -------------------------------------------------
396
-
397
- For your convenience, Phusion Passenger provides a Rack middleware for out-of-band garbage collection. Add the following to your `config.ru`. Likewise, this example code doesn't do anything when the code is not being run in Phusion Passenger, thanks to the `if` block.
398
-
399
- [source, ruby]
400
- ----------------------------------------------------
401
- if defined?(PhusionPassenger)
402
- PhusionPassenger.require_passenger_lib 'rack/out_of_band_gc'
403
-
404
- # Trigger out-of-band GC every 5 requests.
405
- use PhusionPassenger::Rack::OutOfBandGc, 5
406
- end
407
- ----------------------------------------------------
408
-
409
- It should be noted that, although the application uses the Phusion Passenger API, it is <<add_passenger_to_gemfile,*not* necessary to add Phusion Passenger to the Gemfile>>.
410
-
411
- References:
412
-
413
- - link:http://blog.phusion.nl/2013/01/22/phusion-passenger-4-technology-preview-out-of-band-work/[The Phusion Blog article which first introduced this feature.]
186
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/ruby/out_of_band_work.html
414
187
 
415
188
  === Hooks
416
189
 
417
- :version: 4.0.28
418
- include::since_version.txt[]
419
-
420
- Phusion Passenger provides a powerful but simple hooking system, which allows you to extend many aspects of Phusion Passenger's behavior. The hooking system works by executing commands during certain events. Event parameters are passed to the command in the form of environment variables.
421
-
422
- ifdef::apache[]
423
- You can define hooks by setting the configuration option `PassengerCtl hook_<HOOK NAME> <COMMAND TO EXECUTE>`.
424
- endif::apache[]
425
- ifdef::nginx[]
426
- You can define hooks by setting the configuration option `passenger_ctl hook_<HOOK NAME> <COMMAND TO EXECUTE>;`.
427
- endif::nginx[]
428
- ifdef::standalone[]
429
- You can define hooks by <<advanced_configuration,editing the advanced configuration file>>, and adding the configuration option `passenger_ctl hook_<HOOK NAME> <COMMAND TO EXECUTE>;`.
430
- endif::standalone[]
190
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/hooks.html
431
191
 
432
192
  ==== Example
433
193
 
434
- The hook system is best demonstrated with a simple example. In the following example we will hook into the `attached_process` event. This event is called whenever Phusion Passenger has successfully spawned an application processes and added it to the process pool. We print the process's PID and application root.
435
-
436
- First, let's create a script `/home/phusion/attached.sh` which is to be called during the hook.
437
-
438
- [source,sh]
439
- ---------------------------------------------------
440
- #!/bin/sh
441
- echo "Attached process $PASSENGER_PROCESS_PID for app $PASSENGER_APP_ROOT."
442
- ---------------------------------------------------
443
-
444
- Then we make it executable:
445
-
446
- ---------------------------------------------------
447
- chmod +x /home/phusion/attached.sh
448
- ---------------------------------------------------
449
-
450
- And we define the hook in the configuration file:
451
-
452
- ifdef::apache[]
453
- ---------------------------------------------------
454
- PassengerCtl hook_attached_process /home/phusion/attached.sh
455
- ---------------------------------------------------
456
- endif::apache[]
457
- ifdef::nginx[]
458
- ---------------------------------------------------
459
- passenger_ctl hook_attached_process /home/phusion/attached.sh;
460
- ---------------------------------------------------
461
- endif::nginx[]
462
- ifdef::standalone[]
463
- ---------------------------------------------------
464
- passenger_ctl hook_attached_process /home/phusion/attached.sh;
465
- ---------------------------------------------------
466
- endif::standalone[]
467
-
468
- Now restart the web server and access a web app hosted by Phusion Passenger. You should see our message in the web server error log:
469
-
470
- ---------------------------------------------------
471
- [ 2013-12-10 16:12:21.6456 28934/0x1064cb000 Hooks.h:129 ]: Running attached_process hook script: /home/phusion/attached.sh
472
- Attached process 28303 for app /webapps/foobar.
473
- [ 2013-12-10 16:12:21.6580 28934/0x1064cb000 Hooks.h:161 ]: Hook script /home/phusion/attached.sh (PID 28948) exited with status 0
474
- ---------------------------------------------------
194
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/hooks.html#example
475
195
 
476
196
  ==== Environment
477
197
 
478
- A lot of information is passed to hook scripts in the form of environment variables. They are all uppercase and begin with `PASSENGER_`. Some environment variables are passed to all hook scripts, others are passed depending on the hook.
479
-
480
- Here are some of the environment variables which are passed to all hooks, unless documented otherwise:
481
-
482
- * `PASSENGER_HOOK_NAME`
483
- * `PASSENGER_VERSION`
484
- * `PASSENGER_PASSENGER_ROOT`
485
- * `PASSENGER_INSTANCE_DIR`
486
- * `PASSENGER_INSTANCE_REGISTRY_DIR`
198
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/hooks.html#environment
487
199
 
488
200
  ==== Blocking and concurrency
489
201
 
490
- Except when otherwise documented, all hooks block in the background. That is, while your hook command is running, Phusion Passenger can still handle web requests, but the background thread which is running your hook will be blocked and won't be able to perform any further operations. For example, if you wrote a hook script for the `attached_process` event, then Phusion Passenger won't be able to attach further processes until your hook script finishes. You should therefore be careful when writing hook scripts.
491
-
492
- If you have a bug in your script and it blocks, then you will be able to see that using the command `passenger-status --show=backtraces` which prints the backtraces of all threads in the Phusion Passenger core. Look for the `runSingleHookScript` function in the backtrace. The following example shows at line 2 that Phusion Passenger is waiting for the hook script `/home/phusion/badscript.sh`.
493
-
494
- ---------------------------------------------------------------------------------------------------
495
- Thread 'Group process spawner: /home/phusion/webapp.test#default' (0x1062d4000):
496
- in 'bool Passenger::runSingleHookScript(Passenger::HookScriptOptions &, const string &, const vector<pair<string, string> > &)' (Hooks.h:116) -- /home/phusion/badscript.sh
497
- in 'bool Passenger::runHookScripts(Passenger::HookScriptOptions &)' (Hooks.h:159)
498
- in 'void Passenger::ApplicationPool2::Group::spawnThreadRealMain(const SpawnerPtr &, const Passenger::ApplicationPool2::Options &, unsigned int)' (Implementation.cpp:878)
499
- ---------------------------------------------------------------------------------------------------
500
-
501
- Hooks may be called concurrently, because Phusion Passenger sometimes uses multiple background threads. For example, while the `attached_process` hook is being called, a `detached_process` hook may be called, perhaps even for the same application. It is your responsibility to ensure that your hook scripts are concurrency-safe, e.g. by employing locks and other concurrency control techniques.
202
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/hooks.html#blocking-and-concurrency
502
203
 
503
204
  ==== Error handling
504
205
 
505
- If a hook script fails -- that is, if it exits with anything other than exit code 0 -- then the error handling depends on the hook. Some hooks will abort, other hooks will ignore the error. In all cases, the result of the hook script is printed to the log.
206
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/hooks.html#error-handling
506
207
 
507
208
  ==== Compatibility
508
209
 
509
- Because hooks are inherently tied to the implementation of Phusion Passenger, there is no guarantee that hooks that currently work will continue to be available in the future versions of Phusion Passenger. The availability of hooks is very much tied to the specific version of Phusion Passenger.
210
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/hooks.html#compatibility
510
211
 
511
212
  ==== Available hooks
512
213
 
513
- `before_watchdog_initialization`::
514
- Called at the very beginning of Phusion Passenger's life cycle, during the start of the Watchdog process. The first hook is called before initialization is performed (before the Passenger core is started). Errors in the hook script cause Phusion Passenger to abort.
515
- `after_watchdog_initialization`::
516
- Like `before_watchdog_initialization`, but called after initialization of all Phusion Passenger agent processes. Errors in the hook script cause Phusion Passenger to abort.
517
- `before_watchdog_shutdown`::
518
- Called after an exit signal has been noticed (e.g. webserver exit), before the Watchdog starts terminating agents
519
- `after_watchdog_shutdown`::
520
- Called after the Watchdog is done and about to exit
521
- `attached_process`::
522
- Called when Phusion Passenger has successfully spawned an application processes and added it to the process pool. Extra environment variables: `PASSENGER_PROCESS_PID`, `PASSENGER_APP_ROOT`. Errors in the hook script are ignored.
523
- `detached_process`::
524
- Called when Phusion Passenger has removed an application process from the process pool. This could happen when:
525
- +
526
- - The process has crashed, and Phusion Passenger noticed it.
527
- - Phusion Passenger has shut down a process because it's been idle for too long.
528
- - The administrator configured different resource limits, and Phusion Passenger is starting or shutting down processes in response.
529
- - Phusion Passenger itself is shutting down.
530
-
531
- +
532
- Extra environment variables: `PASSENGER_PROCESS_PID`, `PASSENGER_APP_ROOT`. Errors in the hook script are ignored.
533
-
534
- `spawn_failed` (since 4.0.49)::
535
- Called when an application process could not be spawned. This could happen when:
536
- +
537
- - The application failing to start. For example: bugs in the application, database problems causing the application to crash, incorrectly installed dependencies.
538
- - Operating system-level problems, such as running out of memory.
539
- - The application taking too long to start, and hitting Phusion Passenger's timeout.
540
-
541
- +
542
- `queue_full_error` (since 5.0.0 RC 1)::
543
- The server rejects new requests (default: HTTP 503) while the request queue is full (https://www.phusionpassenger.com/documentation/Users%20guide%20Nginx.html#passenger_max_request_queue_size).
544
- This hook gets called for each rejection.
545
- +
546
- Extra environment variables:
547
- +
548
- - `PASSENGER_APP_ROOT`: the path to the application that failed to spawn.
549
- - `PASSENGER_APP_GROUP_NAME`: the configured app group name.
550
- - `PASSENGER_ERROR_MESSAGE`: an error message that describes the problem.
551
- - `PASSENGER_ERROR_ID`: a unique ID for this error event. If you search for this ID in the web server error log files, you should be able to find details about the error.
552
- - `PASSENGER_APP_ERROR_MESSAGE`: output captured from the application at the time the error occurred.
553
-
554
- +
555
- This hook does not block because it's always run in an extra background thread. Errors in the hook script are ignored.
556
-
557
- `max_request_time_reached` (since 5.0.2, Enterprise-only)::
558
- Called when a <<PassengerMaxRequestTime,max request time limit>> has been reached. Please note that as soon as this hook has finished executing, the application process will be killed with SIGKILL. So if you want to perform any diagnostics on the process in question (e.g. with strace, gdb, etc), please do not exit your hook script until you've obtained all the diagnostics you want.
559
- +
560
- Extra environment variables:
561
- +
562
- - `PASSENGER_APP_ID`: the PID of the process whose request took too long.
563
- - `PASSENGER_REQUEST_PATH`: the path of the request that took took long, e.g. "/photos/edit?id=123".
564
- - `PASSENGER_REQUEST_HOST`: the host name of the request that took too long, e.g. "www.example.com". This environment variable is not set if the request doesn't contain a Host header.
214
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/indepth/hooks.html#available-hooks
565
215
 
566
216
  [[flying_passenger]]
567
217
  === Flying Passenger
218
+
568
219
  ifdef::apache[]
569
- :version: 4.0.45
570
- include::enterprise_only.txt[]
571
- endif::apache[]
220
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/flying_passenger.html
221
+ endif::[]
572
222
  ifdef::nginx[]
573
- :version: 4.0.6
574
- include::enterprise_only.txt[]
575
- endif::nginx[]
576
-
577
- Flying Passenger allows one to decouple Phusion Passenger's life time from the web server's life time, so that the web server can be independently restarted from Phusion Passenger, and from any of the application processes served by Phusion Passenger.
578
-
579
- Normally, Phusion Passenger starts together with the web server, and shuts down together with the web server. The advantages of this default behavior is that it makes Phusion Passenger easy to administer: one only has to deal with the web server process and can expect all relevant processes to be cleaned up after a web server shut down. However this also brings about a disadvantage: every time one restarts the web server (e.g. to make a minor configuration change), Phusion Passenger and all its application processes also get restarted.
580
-
581
- This problem is solved by 'Flying Passenger', which is an advanced mode of operation in Phusion Passenger that allows the web server to be indepedently restarted from Phusion Passenger. When this mode is enabled:
582
-
583
- - One must start Phusion Passenger separately from the web server, namely by starting the Flying Passenger daemon. This daemon must - to an extent - be separately configured and managed from the web server.
584
- - The web server must be configured to forward requests to the Flying Passenger daemon.
585
- - You should beware of the <<flying_passenger_caveats,caveats and limitations>>.
223
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/flying_passenger.html
224
+ endif::[]
225
+ ifdef::standalone[]
226
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/flying_passenger.html
227
+ endif::[]
586
228
 
587
229
  ==== Requirements
588
230
 
589
- Before you can use the Flying Passenger feature, you must have Phusion Passenger for
590
231
  ifdef::apache[]
591
- Apache
592
- endif::apache[]
232
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/flying_passenger.html
233
+ endif::[]
593
234
  ifdef::nginx[]
594
- Nginx
595
- endif::nginx[]
596
- properly installed.
235
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/flying_passenger.html
236
+ endif::[]
237
+ ifdef::standalone[]
238
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/flying_passenger.html
239
+ endif::[]
597
240
 
598
241
  ==== Basic usage
599
242
 
600
- Start the Flying Passenger daemon by invoking the `flying-passenger` command. The only required option is `--socket-file`. Depending on whether you wish to enable <<user_switching,User Switching>>, you have to start `flying-passenger` with root privileges or not.
601
-
602
- -------------------
603
- $ sudo flying-passenger --socket-file=/var/run/flying-passenger.sock
604
- I, [2013-06-14T09:10:13.095339 #77179] INFO -- : Welcome to Flying Passenger 4.1.0
605
- I, [2013-06-14T09:10:13.095339 #77179] INFO -- : Starting PassengerWatchdog...
606
- I, [2013-06-14T09:10:13.097036 #77179] INFO -- : PassengerWatchdog started on PID 77181
607
- ...
608
- I, [2013-06-14T09:10:13.129017 #77179] INFO -- : PassengerWatchdog initialized properly
609
- I, [2013-06-14T09:10:13.129127 #77179] INFO -- : Flying Passenger up and listening on /var/run/flying-passenger.sock!
610
- -------------------
611
-
612
- Now configure the web server to make use of the Flying Passenger daemon,
613
- ifdef::apache[]
614
- by setting the `PassengerFlyWith` option to the socket filename:
615
-
616
- -------------------
617
- PassengerFlyWith /var/run/flying-passenger.sock
618
- -------------------
619
- endif::apache[]
620
- ifdef::nginx[]
621
- by setting the `passenger_fly_with` option to the socket filename:
622
-
623
- -------------------
624
- http {
625
- ...
626
- passenger_fly_with /var/run/flying-passenger.sock;
627
- ...
628
- }
629
- -------------------
630
- endif::nginx[]
631
-
632
- After (re)starting
633
243
  ifdef::apache[]
634
- Apache, Apache + Flying Passenger is fully operational:
635
-
636
- -------------------
637
- $ sudo service apache2 restart
638
- -------------------
639
- endif::apache[]
640
- ifdef::nginx[]
641
- Nginx, Nginx + Flying Passenger is fully operational:
642
-
643
- -------------------
644
- $ sudo /path-to/nginx
645
- -------------------
646
- endif::nginx[]
647
- Flying Passenger is fully operational:
648
-
649
- You can test it by adding a virtual host for a web app:
650
-
651
- ifdef::apache[]
652
- -------------------
653
- <VirtualHost *:80>
654
- ServerName www.foo.local
655
- DocumentRoot /webapps/foo/public
656
- </VirtualHost>
657
- -------------------
658
- endif::apache[]
659
- ifdef::nginx[]
660
- -------------------
661
- http {
662
- ...
663
-
664
- server {
665
- listen 80;
666
- server_name www.foo.local;
667
- root /webapps/foo/public;
668
- passenger_enabled on;
669
- }
670
- }
671
- -------------------
672
- endif::nginx[]
673
-
674
- Verify that it works by making an HTTP request to it:
675
-
676
- ---------------------------------
677
- $ curl http://www.foo.local/
678
- ---------------------------------
679
-
680
- Now let's verify that restarting the web server does not restart the just-spawned application process. Run `passenger-status` to obtain the PID of the application process:
681
-
682
- ---------------------------------
683
- $ sudo passenger-status
684
- Version: 4.1.0
685
- Date : 2013-06-14 09:21:51 -0400
686
- .---------- General information -----------
687
- Max pool size : 6
688
- Processes : 1
689
- Requests in top-level queue : 0
690
-
691
- .---------- Application groups -----------
692
- /webapps/foo#default:
693
- App root: /webapps/foo
694
- Requests in queue: 0
695
- * PID: 77283 Sessions: 0 Processed: 1 Uptime: 2s
696
- CPU: 1% Memory : 8M Last used: 2s ago
697
- ---------------------------------
698
-
699
- As you can see, the PID of the application process is **77283**. Now let's see what happens if we restart the web server:
700
-
701
- ifdef::apache[]
702
- ------------------------
703
- $ sudo service apache2 restart
704
- $ sudo passenger-status
705
- ------------------------
706
- endif::apache[]
244
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/flying_passenger.html
245
+ endif::[]
707
246
  ifdef::nginx[]
708
- ------------------------
709
- $ sudo /path-to/nginx -s stop
710
- $ sudo /path-to/nginx
711
- $ sudo passenger-status
712
- ------------------------
713
- endif::nginx[]
714
-
715
- The application process should remain there, unchanged:
716
-
717
- ---------------------------------
718
- $ sudo passenger-status
719
- Version: 4.1.0
720
- Date : 2013-06-14 09:21:51 -0400
721
- .---------- General information -----------
722
- Max pool size : 6
723
- Processes : 1
724
- Requests in top-level queue : 0
725
-
726
- .---------- Application groups -----------
727
- /webapps/foo#default:
728
- App root: /webapps/foo
729
- Requests in queue: 0
730
- * PID: 77283 Sessions: 0 Processed: 1 Uptime: 18s
731
- CPU: 1% Memory : 8M Last used: 18s ago
732
- ---------------------------------
247
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/flying_passenger.html
248
+ endif::[]
249
+ ifdef::standalone[]
250
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/flying_passenger.html
251
+ endif::[]
733
252
 
734
253
  [[configuring_flying_passenger]]
735
254
  ==== Configuring Flying Passenger
736
255
 
737
- Flying Passenger gets *some* configuration from the web server, but not all. In particular, most web server directives that are only valid in the
738
- ifdef::apache[]
739
- global context, e.g. <<PassengerLogLevel,PassengerLogLevel>>,
740
- endif::apache[]
741
- ifdef::nginx[]
742
- `http` context, e.g. <<PassengerLogLevel,passenger_log_level>>,
743
- endif::nginx[]
744
- have no effect when using Flying Passenger. Instead, you are supposed to pass these configuration directives through command line options to the Flying Passenger daemon. Configuration directives that have no effect on Flying Passenger are documented as such. You can assume that configuration directives that are not documented as such, work fine on Flying Passenger.
745
-
746
- For example, to achieve the same effect as setting
747
256
  ifdef::apache[]
748
- `PassengerLogLevel`
749
- endif::apache[]
257
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/flying_passenger.html
258
+ endif::[]
750
259
  ifdef::nginx[]
751
- `passenger_log_level`
752
- endif::nginx[]
753
- to 2, run the Flying Passenger daemon as follows:
754
-
755
- ----------------------------------
756
- $ sudo flying-passenger --socket-file=/var/run/flying-passenger.sock --log-level=2
757
- ----------------------------------
758
-
759
- Currently, not all configuration directives have a Flying Passenger equivalent. Run the following command to see an overview of available options:
760
-
761
- ----------------------------
762
- $ flying-passenger --help
763
- ----------------------------
260
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/flying_passenger.html
261
+ endif::[]
262
+ ifdef::standalone[]
263
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/flying_passenger.html
264
+ endif::[]
764
265
 
765
266
  ==== Managing the Flying Passenger daemon
766
267
 
767
- The Flying Passenger daemon runs in the foreground by default. This is undesirable on server environments. You can make it go into the background by passing `--daemonize`, `--log-file` and `--pid-file`:
768
-
769
- --------------------------------------------------------------------------------
770
- $ sudo flying-passenger --socket-file=/var/run/flying-passenger.sock \
771
- --daemonize --log-file=/var/log/flying-passenger.log \
772
- --pid-file=/var/run/flying-passenger.pid
773
- --------------------------------------------------------------------------------
774
-
775
- You can shut down a Flying Passenger daemon by sending SIGINT or SIGTERM to it:
776
-
777
- --------------------------------------------------------------------------------
778
- $ kill `cat /var/run/flying-passenger.pid`
779
- --------------------------------------------------------------------------------
780
-
781
- We recommend using link:http://cr.yp.to/daemontools.html[daemontools] or link:http://smarden.org/runit/[runit] for managing the Flying Passenger daemon. These tools will allow automatically starting the Flying Passenger daemon at boot, and will automatically restart the daemon if it crashes. You can create and enable a daemontools/runit service as folows:
782
-
783
- --------------------------------
784
- $ sudo mkdir /etc/service/flying-passenger
785
- $ sudo nano /etc/service/flying-passenger/run
786
- #!/bin/sh
787
- exec /path-to/flying-passenger \
788
- --socket-file=/var/run/flying-passenger.sock \
789
- --log-file=/var/log/flying-passenger.log \
790
- --pid-file=/var/run/flying-passenger.pid
791
- --------------------------------
792
-
793
- Immediately after creating the `run` file, daemontools/runit automatically runs it to start the daemon. Note that the location (`/etc/service`) depends on the OS or Linux distros. Sometimes it's `/service`. Also note that we start the Flying Passenger daemon without `--daemonize`.
794
-
795
- To shut down a daemontools/runit-managed daemon, you need to use `svc -d /etc/service/flying-passenger` (daemontools) or `sv stop /etc/service/flying-passenger` (runit) instead of sending a signal to the process.
268
+ ifdef::apache[]
269
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/flying_passenger.html
270
+ endif::[]
271
+ ifdef::nginx[]
272
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/flying_passenger.html
273
+ endif::[]
274
+ ifdef::standalone[]
275
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/flying_passenger.html
276
+ endif::[]
796
277
 
797
278
  [[using_flying_passenger_with_mri_18_or_jruby]]
798
279
  ==== Using Flying Passenger with MRI 1.8 or JRuby
799
280
 
800
- Using Flying Passenger in combination with MRI Ruby 1.8 or with JRuby requires special attention. This is because the Flying Passenger daemon is written in Ruby, and requires proper `Process.spawn` support, which neither MRI 1.8 nor JRuby support.
801
-
802
- It is however possible to use Flying Passenger with MRI Ruby 1.8 and JRuby. You can't run the Flying Passenger daemon in MRI 1.8 or JRuby, but you can still run the web applications - hosted under Flying Passenger - in MRI 1.8 or JRuby.
803
-
804
- First, edit your web server configuration file and specify a Ruby interpreter for your web applications. For example:
805
-
806
281
  ifdef::apache[]
807
- --------------------
808
- # Connect to the Flying Passenger daemon on the following socket
809
- PassengerFlyWith /var/run/flying-passenger.sock
810
- ...
811
-
812
- <VirtualHost *:80>
813
- ServerName www.foo.com
814
- DocumentRoot /webapps/foo/public
815
- # Use JRuby for this web application
816
- PassengerRuby /opt/jruby/bin/jruby
817
- </VirtualHost>
818
- --------------------
819
- endif::apache[]
282
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/flying_passenger.html
283
+ endif::[]
820
284
  ifdef::nginx[]
821
- --------------------
822
- # Connect to the Flying Passenger daemon on the following socket
823
- passenger_fly_with /var/run/flying-passenger.sock;
824
- ...
825
-
826
- server {
827
- listen 80;
828
- server_name www.foo.com;
829
- root /webapps/foo/public;
830
- passenger_enabled on;
831
- # Use JRuby for this web application
832
- passenger_ruby /opt/jruby/bin/jruby;
833
- }
834
- --------------------
835
- endif::nginx[]
836
-
837
- Then you need to install a Ruby 1.9-compatible Ruby interpreter with POSIX spawn support, alongside JRuby/MRI 1.8. Ruby interpreters which can be used for running the Flying Passenger daemon include:
838
-
839
- * MRI Ruby >= 1.9.
840
- * Rubinius.
841
-
842
- The following example demonstrates how you can install MRI Ruby 1.9 in parallel with your MRI Ruby 1.8 or JRuby installation.
843
-
844
- Example for Debian/Ubuntu users:
845
-
846
- [source,sh]
847
- --------------------------------
848
- # Install Ruby 1.9
849
- sudo apt-get install ruby1.9.3
850
- # Run the Flying Passenger daemon in Ruby 1.9
851
- ruby1.9 -S flying-passenger --socket-file=/var/run/flying-passenger.sock
852
- --------------------------------
853
-
854
- Example for RVM users:
855
-
856
- [source,sh]
857
- --------------------------------
858
- # Install Ruby 1.9
859
- rvm install 1.9.3
860
- # Run the Flying Passenger daemon in Ruby 1.9
861
- $ rvm-exec 1.9.3 ruby -S flying-passenger --socket-file=/var/run/flying-passenger.sock
862
- --------------------------------
863
-
864
- The Flying Passenger daemon will now be run on Ruby 1.9, while the web application 'www.foo.com' will be run on JRuby.
285
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/flying_passenger.html
286
+ endif::[]
287
+ ifdef::standalone[]
288
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/flying_passenger.html
289
+ endif::[]
865
290
 
866
291
  [[flying_passenger_caveats]]
867
292
  ==== Caveats and limitations
868
293
 
869
- Beware of the following caveats and limitations when using Flying Passenger:
870
-
871
- ifdef::apache[]
872
- - The Phusion Passenger module that is loaded into Apache, **must** be of the same version as the Flying Passenger daemon. Failing to meet this requirement may result in cryptic errors, or may result in certain features not working, until you've fixed the situation. When upgrading Phusion Passenger, you must restart both Apache and the Flying Passenger daemon.
873
- - The <<PassengerRoot,PassengerRoot>> directive has no effect. When using Flying Passenger, you are not supposed to set `PassengerRoot`.
874
- endif::apache[]
875
- ifdef::nginx[]
876
- - The Nginx executable **must** be compiled with the same version of Phusion Passenger as the Flying Passenger daemon. Failing to meet this requirement may result in cryptic errors, or may result in certain features not working, until you've fixed the situation. When upgrading Phusion Passenger, you must restart both Nginx and the Flying Passenger daemon.
877
- - The <<PassengerRoot,passenger_root>> directive has no effect. When using Flying Passenger, you are not supposed to set `passenger_root`.
878
- endif::nginx[]
879
- - The Flying Passenger daemon is written in Ruby. It requires a Ruby interpreter with proper `Process#spawn` support. At the time of writing, all Ruby interpreters in existance satisfy this requirement, except for MRI Ruby 1.8 and JRuby. See <<using_flying_passenger_with_mri_18_or_jruby,Using Flying Passenger with MRI 1.8 or JRuby>> for more information.
880
- - When you add a new application to the web server configuration, Flying Passenger will automatically pick up the application's settings and spawn this new application upon the first request to it. However it is not capable of automatically starting the new app before a request has been sent to it (i.e.
881
294
  ifdef::apache[]
882
- <<PassengerPreStart,PassengerPreStart>>-like
883
- endif::apache[]
884
- ifdef::nginx[]
885
- <<PassengerPreStart,passenger_pre_start>>-like
886
- endif::nginx[]
887
- behavior is not available in this case). As a workaround, you can send an HTTP request to your application after starting the daemon, which forces it to spawn application processes.
888
- - When you remove an application from the web server configuration, Flying Passenger will not detect the removal and will not shut down the associated application processes. Killing the application processes will also not help, because Flying Passenger will restart them per the (now-removed, but still in the Flying Passenger daemon's memory)
889
- ifdef::apache[]
890
- <<PassengerMinInstances,PassengerMinInstances>>
891
- endif::apache[]
892
- ifdef::nginx[]
893
- <<PassengerMinInstances,passenger_min_instances>>
894
- endif::nginx[]
895
- settings. At the moment, there are two ways to get rid of those processes:
896
- +
897
- ifdef::apache[]
898
- * Before removing the application from the web server configuration, explicitly set its `PassengerMinInstances` to 0. Next, send a request to it, which will cause the Flying Passenger daemon to take over the new `PassengerMinInstances 0` option. You can then proceed with removing the application from the web server configuration, and restarting the web server. Finally, kill the PIDs associated to those application processes and remove the application configuration.
899
- endif::apache[]
295
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/apache/flying_passenger.html
296
+ endif::[]
900
297
  ifdef::nginx[]
901
- * Before removing the application from the web server configuration, explicitly set its `passenger_min_instances` to 0. Next, send a request to it, which will cause the Flying Passenger daemon to take over the new `passenger_min_instances 0` option. You can then proceed with removing the application from the web server configuration, and restarting the web server. Finally, kill the PIDs associated to those application processes and remove the application configuration.
902
- endif::nginx[]
903
- * Restart the Flying Passenger daemon.
298
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/flying_passenger.html
299
+ endif::[]
300
+ ifdef::standalone[]
301
+ This documentation has moved. Please visit https://www.phusionpassenger.com/library/deploy/nginx/flying_passenger.html
302
+ endif::[]