← Back to branch summary

~ubuntu-branches/ubuntu/wily/ruby-passenger/wily-proposed

« back to all changes in this revision

Viewing changes to doc/users_guide_snippets/tips.txt

  • Committer: Package Import Robot
  • Author(s): Felix Geyer
  • Date: 2013-11-23 23:50:02 UTC
  • mfrom: (1.1.4)
  • Revision ID: package-import@ubuntu.com-20131123235002-8fdhsq7afj15o2z2
Tags: 4.0.25-1
http://bugs.debian.org/725591
* New upstream release.
* Refresh fix_install_path.patch.
* Build for Ruby 2.0 instead of 1.8. (Closes: #725591)
* Add fix_ftbfs_fortify_source.patch.
* Install passenger template files.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/users_guide_snippets/tips.txt
314
314
please refer to
315
315
link:http://api.rubyonrails.org/classes/ActionView/Helpers/AssetTagHelper.html[the Rails API docs].
316
316
 
317
 
=== Out-of-Band Garbage Work and Out-of-Band Garbage Collection
 
317
=== Out-of-Band Work and Out-of-Band Garbage Collection
318
318
 
319
319
**Available since Phusion Passenger 4.0.0.**
320
320
 
328
328
 
329
329
- 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.
330
330
- 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.
 
331
- Phusion Passenger guarantees that no more than 1 process is performing out-of-band work at the same time.
331
332
 
332
333
Applications can use Out-of-Band Work as follows:
333
334
 
334
 
1. Request out-of-band work by outputting the `X-Passenger-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.
335
 
2. You can actually perform out-of-band work when you receive a `:oob_work` Phusion Passenger event.
 
335
1. Ensure that
 
336
ifdef::apache[]
 
337
<<PassengerMaxPoolSize,PassengerMaxPoolSize>>
 
338
and
 
339
<<PassengerMinInstances,PassengerMinInstances>>
 
340
endif::[]
 
341
ifdef::nginx[]
 
342
<<PassengerMaxPoolSize,passenger_max_pool_size>>
 
343
and
 
344
<<PassengerMinInstances,passenger_min_instances>>
 
345
endif::[]
 
346
are both larger than 1. Out-of-band work only works if there are at least 2 application processes.
 
347
2. Request out-of-band work by outputting the `X-Passenger-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.
 
348
3. You can actually perform out-of-band work when you receive a `:oob_work` Phusion Passenger event.
336
349
 
337
350
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.
338
351
 
538
551
 
539
552
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.
540
553
 
 
554
[[using_flying_passenger_with_mri_18_or_jruby]]
 
555
==== Using Flying Passenger with MRI 1.8 or JRuby
 
556
 
 
557
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.
 
558
 
 
559
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.
 
560
 
 
561
First, edit your Nginx configuration file and specify a Ruby interpreter for your web applications. For example:
 
562
 
 
563
--------------------
 
564
# Connect to the Flying Passenger daemon on the following socket
 
565
passenger_fly_with /var/run/flying-passenger.sock;
 
566
...
 
567
 
 
568
server {
 
569
    listen 80;
 
570
    server_name www.foo.com;
 
571
    root /webapps/foo/public;
 
572
    passenger_enabled on;
 
573
    # Use JRuby for this web application
 
574
    passenger_ruby /opt/jruby/bin/jruby;
 
575
}
 
576
--------------------
 
577
 
 
578
Then you need to install a Ruby 1.9-compatible Ruby interpeter with POSIX spawn support, alongside JRuby/MRI 1.8. Ruby interpreters which can be used for running the Flying Passenger daemon include:
 
579
 
 
580
 * MRI Ruby >= 1.9.
 
581
 * Rubinius.
 
582
 
 
583
The following example demonstrates how you can install MRI Ruby 1.9 in parallel with your MRI Ruby 1.8 or JRuby installation.
 
584
 
 
585
Example for Debian/Ubuntu users:
 
586
 
 
587
[source,sh]
 
588
--------------------------------
 
589
# Install Ruby 1.9
 
590
sudo apt-get install ruby1.9.3
 
591
# Run the Flying Passenger daemon in Ruby 1.9
 
592
ruby1.9 -S flying-passenger --socket-file=/var/run/flying-passenger.sock
 
593
--------------------------------
 
594
 
 
595
Example for RVM users:
 
596
 
 
597
[source,sh]
 
598
--------------------------------
 
599
# Install Ruby 1.9
 
600
rvm install 1.9.3
 
601
# Run the Flying Passenger daemon in Ruby 1.9
 
602
$ rvm-exec 1.9.3 ruby -S flying-passenger --socket-file=/var/run/flying-passenger.sock
 
603
--------------------------------
 
604
 
 
605
The Flying Passenger daemon will now be run on Ruby 1.9, while the web application 'www.foo.com' will be run on JRuby.
 
606
 
541
607
[[flying_passenger_caveats]]
542
608
==== Caveats and limitations
543
609
 
545
611
 
546
612
- 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.
547
613
- The <<PassengerRoot,passenger_root>> directive has no effect. When using Flying Passenger, you are not supposed to set `passenger_root`.
 
614
- 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.
548
615
- 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. <<PassengerPreStart,passenger_pre_start>>-like 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.
549
616
- 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) <<PassengerMinInstances,passenger_min_instances>> settings. At the moment, there are two ways to get rid of those processes:
550
617
  * 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.